0
# PhantomJS Prebuilt
1
2
PhantomJS Prebuilt is an NPM installer and Node.js wrapper for PhantomJS, a headless WebKit browser with JavaScript API capabilities. This package automatically downloads and manages prebuilt PhantomJS binaries for different platforms during installation, eliminating the need for manual compilation. It provides both command-line access and programmatic integration via Node.js, making it easy to incorporate headless browser automation into JavaScript applications.
3
4
## Package Information
5
6
- **Package Name**: phantomjs-prebuilt
7
- **Package Type**: npm
8
- **Language**: JavaScript (Node.js)
9
- **Installation**: `npm install phantomjs-prebuilt`
10
11
## Core Imports
12
13
```javascript
14
const phantomjs = require('phantomjs-prebuilt');
15
```
16
17
For ES6 modules (if using with bundlers that support CommonJS):
18
19
```javascript
20
import phantomjs from 'phantomjs-prebuilt';
21
```
22
23
## Basic Usage
24
25
### Programmatic Usage with Node.js
26
27
```javascript
28
const phantomjs = require('phantomjs-prebuilt');
29
const childProcess = require('child_process');
30
const path = require('path');
31
32
// Get the path to the PhantomJS binary
33
const binPath = phantomjs.path;
34
35
// Execute a PhantomJS script
36
const childArgs = [
37
path.join(__dirname, 'my-phantom-script.js'),
38
'script-argument-1',
39
'script-argument-2'
40
];
41
42
childProcess.execFile(binPath, childArgs, function(err, stdout, stderr) {
43
if (err) {
44
console.error('PhantomJS execution error:', err);
45
return;
46
}
47
console.log('Script output:', stdout);
48
console.error('Script errors:', stderr);
49
});
50
```
51
52
### Command Line Usage
53
54
After installation, the `phantomjs` command is available:
55
56
```bash
57
# Run PhantomJS with a script
58
phantomjs my-script.js
59
60
# Run with arguments
61
phantomjs --load-images=no my-script.js arg1 arg2
62
63
# Check PhantomJS version
64
phantomjs --version
65
```
66
67
## Architecture
68
69
PhantomJS Prebuilt is built around several key components designed to handle cross-platform binary distribution and Node.js integration:
70
71
- **Installation System**: Automated download and extraction of platform-specific PhantomJS binaries during npm install, with support for custom CDN mirrors and proxy configurations
72
- **Binary Management**: Dynamic path resolution and platform detection system that locates the correct executable based on the target operating system and architecture
73
- **CLI Wrapper**: Node.js wrapper script that forwards all arguments and streams to the underlying PhantomJS binary while handling process lifecycle and signal management
74
- **Cross-Platform Support**: Automatic detection of Windows, macOS, and Linux platforms with appropriate binary selection and path handling
75
- **PATH Utilities**: Helper functions to avoid conflicts with other npm-installed binaries and provide clean environment setup
76
77
The package follows a "download-once, use-anywhere" pattern where the binary is fetched during installation and made available both programmatically via the Node.js API and through the global `phantomjs` command.
78
79
## Capabilities
80
81
### Binary Path Access
82
83
Get the absolute path to the PhantomJS executable for programmatic usage.
84
85
```javascript { .api }
86
/**
87
* Path to the PhantomJS binary executable
88
* @type {string|null} - Absolute path to binary, null during installation
89
*/
90
phantomjs.path
91
```
92
93
### Platform Information
94
95
Access platform and architecture information for the installed binary.
96
97
```javascript { .api }
98
/**
99
* Target platform identifier for the PhantomJS binary
100
* @type {string|undefined} - Platform string (e.g., 'linux', 'darwin', 'win32')
101
*/
102
phantomjs.platform
103
104
/**
105
* Target architecture identifier for the PhantomJS binary
106
* @type {string|undefined} - Architecture string (e.g., 'x64', 'ia32')
107
*/
108
phantomjs.arch
109
```
110
111
### Version Information
112
113
Get the version of PhantomJS provided by this package.
114
115
```javascript { .api }
116
/**
117
* Version of PhantomJS binary provided by this package
118
* @type {string} - Version string (currently '2.1.1')
119
*/
120
phantomjs.version
121
```
122
123
### PATH Utilities
124
125
Utility function for cleaning PATH environment variables to avoid conflicts.
126
127
```javascript { .api }
128
/**
129
* Removes node_modules bin directories and ./bin from PATH to avoid conflicts
130
* @param {string} path - PATH environment variable string to clean
131
* @returns {string} - Cleaned PATH string
132
*/
133
phantomjs.cleanPath(path)
134
```
135
136
**Usage Example:**
137
138
```javascript
139
const phantomjs = require('phantomjs-prebuilt');
140
141
// Clean PATH to avoid npm-installed phantom conflicts
142
const cleanedPath = phantomjs.cleanPath(process.env.PATH);
143
console.log('Original PATH:', process.env.PATH);
144
console.log('Cleaned PATH:', cleanedPath);
145
```
146
147
### Command Line Interface
148
149
The package provides a global `phantomjs` command that forwards all arguments to the PhantomJS binary.
150
151
```bash { .api }
152
# Global command available after npm install
153
phantomjs [phantom-arguments...]
154
```
155
156
The CLI wrapper handles:
157
- **stdio forwarding**: All input/output streams are properly connected
158
- **exit code propagation**: Returns the same exit code as PhantomJS
159
- **signal handling**: Forwards SIGTERM signals for clean shutdown
160
- **error reporting**: Provides clear error messages for execution failures
161
162
## Installation Configuration
163
164
The package supports several environment variables for customizing the installation process:
165
166
### Custom Download Mirror
167
168
```bash
169
# Set custom CDN URL for downloading PhantomJS
170
PHANTOMJS_CDNURL=https://bitbucket.org/ariya/phantomjs/downloads npm install phantomjs-prebuilt
171
172
# Or configure via npm config
173
npm config set phantomjs_cdnurl https://bitbucket.org/ariya/phantomjs/downloads
174
```
175
176
### Platform Override
177
178
```bash
179
# Install for specific platform/architecture
180
PHANTOMJS_PLATFORM=linux PHANTOMJS_ARCH=x64 npm install phantomjs-prebuilt
181
```
182
183
## Error Handling
184
185
### Common Installation Issues
186
187
**ENOENT spawn errors**: Usually indicates `node` or `tar` not on PATH
188
**EPERM permission errors**: Insufficient write access or antivirus interference
189
**ECONNRESET network errors**: Download failures, try custom CDN URL
190
191
### Runtime Error Detection
192
193
```javascript
194
const phantomjs = require('phantomjs-prebuilt');
195
const childProcess = require('child_process');
196
197
if (!phantomjs.path) {
198
console.error('PhantomJS binary not available (still installing?)');
199
process.exit(1);
200
}
201
202
const child = childProcess.execFile(phantomjs.path, ['--version'], (err, stdout, stderr) => {
203
if (err) {
204
console.error('Failed to execute PhantomJS:', err.message);
205
return;
206
}
207
console.log('PhantomJS version:', stdout.trim());
208
});
209
210
child.on('error', (err) => {
211
console.error('PhantomJS process error:', err);
212
});
213
```
214
215
## Cross-Platform Considerations
216
217
- **Automatic platform detection**: Downloads appropriate binary for current OS/architecture
218
- **Repository rebuilding**: Run `npm rebuild` when working across different platforms
219
- **Manual binary detection**: Automatically uses existing PhantomJS on PATH for non-global installs
220
- **Platform-specific paths**: Binary executable names vary by platform (`.exe` on Windows)
221
222
## Types
223
224
```javascript { .api }
225
/**
226
* Main module exports object
227
*/
228
interface PhantomJSModule {
229
/** Path to PhantomJS binary, null during installation */
230
path: string | null;
231
/** Platform identifier for installed binary */
232
platform?: string;
233
/** Architecture identifier for installed binary */
234
arch?: string;
235
/** PhantomJS version provided by this package */
236
version: string;
237
/** Utility to clean PATH environment variable */
238
cleanPath(path: string): string;
239
}
240
```