0
# PhantomJS
1

2
PhantomJS is an NPM installer and wrapper for the PhantomJS headless WebKit browser with JavaScript API. This package automatically downloads and installs a platform-specific PhantomJS binary and provides Node.js utilities to locate and execute PhantomJS programmatically. It enables headless browser automation, web scraping, testing, and server-side browser capabilities without requiring a GUI.
3

4
## Package Information
5

6
- **Package Name**: phantomjs
7
- **Package Type**: npm
8
- **Language**: JavaScript (Node.js)
9
- **Installation**: `npm install phantomjs`
10

11
## Core Imports
12

13
```javascript
14
const phantomjs = require('phantomjs');
15
```
16

17
For ES modules (if supported in your environment):
18

19
```javascript
20
import phantomjs from 'phantomjs';
21
```
22

23
## Basic Usage
24

25
```javascript
26
const phantomjs = require('phantomjs');
27
const childProcess = require('child_process');
28
const path = require('path');
29

30
// Get the path to the PhantomJS binary
31
const binPath = phantomjs.path;
32

33
// Execute a PhantomJS script
34
const scriptPath = path.join(__dirname, 'my-script.js');
35
const childArgs = [scriptPath, 'arg1', 'arg2'];
36

37
childProcess.execFile(binPath, childArgs, function(err, stdout, stderr) {
38
  if (err) {
39
    console.error('PhantomJS execution failed:', err);
40
    return;
41
  }
42
  console.log('PhantomJS output:', stdout);
43
});
44
```
45

46
## Capabilities
47

48
### Binary Path Access
49

50
Provides the absolute path to the installed PhantomJS binary executable.
51

52
```javascript { .api }
53
/**
54
 * Absolute path to the PhantomJS binary executable.
55
 * Returns null if the binary is not yet installed (e.g., during installation).
56
 */
57
phantomjs.path; // {string|null}
58
```
59

60
### Platform Information
61

62
Provides information about the target platform and architecture.
63

64
```javascript { .api }
65
/**
66
 * Target platform identifier (e.g., 'linux', 'darwin', 'win32').
67
 * May be undefined if location module fails to load during installation.
68
 */
69
phantomjs.platform; // {string|undefined}
70

71
/**
72
 * Target architecture identifier (e.g., 'x64', 'ia32').
73
 * May be undefined if location module fails to load during installation.
74
 */
75
phantomjs.arch; // {string|undefined}
76
```
77

78
### Version Information
79

80
Provides the version of the PhantomJS binary installed by this package.
81

82
```javascript { .api }
83
/**
84
 * Version string of the PhantomJS binary installed by this package.
85
 * Note: This is the PhantomJS binary version (e.g., '1.9.8'), 
86
 * which may differ from the npm package version.
87
 */
88
phantomjs.version; // {string}
89
```
90

91
### PATH Utilities
92

93
Utility function to clean PATH environment variable by removing node_modules and ./bin entries.
94

95
```javascript { .api }
96
/**
97
 * Removes node_modules and ./bin entries from a PATH string to avoid
98
 * conflicts with npm-installed binaries.
99
 * @param {string} path - PATH environment variable string  
100
 * @returns {string} Cleaned PATH string
101
 */
102
phantomjs.cleanPath(path);
103
```
104

105
**Usage Example:**
106

107
```javascript
108
const phantomjs = require('phantomjs');
109

110
// Clean the current PATH
111
const originalPath = process.env.PATH;
112
const cleanedPath = phantomjs.cleanPath(originalPath);
113

114
console.log('Original PATH:', originalPath);
115
console.log('Cleaned PATH:', cleanedPath);
116

117
// Use cleaned PATH to avoid finding npm-installed binaries
118
process.env.PATH = cleanedPath;
119
```
120

121
### Command Line Interface
122

123
The package also provides a command-line executable that forwards all arguments to the PhantomJS binary.
124

125
```bash
126
# Direct execution via npm bin linking
127
phantomjs --version
128
phantomjs script.js arg1 arg2
129

130
# Or via npx
131
npx phantomjs --version
132
```
133

134
## Architecture
135

136
The phantomjs package consists of several key components:
137

138
- **Installation System**: Downloads and installs platform-specific PhantomJS binaries during `npm install`
139
- **Binary Wrapper**: Command-line script (`bin/phantomjs`) that spawns the actual PhantomJS binary with stdio forwarding
140
- **Node.js API**: Programmatic interface for accessing binary path and platform information
141
- **Cross-platform Support**: Automatic binary selection and installation for Linux, macOS, and Windows
142

143
## Error Handling
144

145
- `phantomjs.path` returns `null` if the binary is not installed (typically during installation)
146
- `phantomjs.platform` and `phantomjs.arch` may be `undefined` if the location module fails to load during installation
147
- File system permission errors during binary permission setting are silently ignored
148
- Binary execution errors should be handled when using `childProcess.execFile()`
149
- The package uses try/catch internally to handle missing location.js file gracefully
150

151
## Configuration
152

153
The package supports several environment variables and npm configuration options:
154

155
- **PHANTOMJS_CDNURL**: Override the download CDN URL
156
- **PHANTOMJS_PLATFORM**: Override target platform detection
157
- **PHANTOMJS_ARCH**: Override target architecture detection
158
- **npm config phantomjs_cdnurl**: Set CDN URL via npm config
159

160
**Example:**
161

162
```bash
163
# Install with custom CDN
164
npm install phantomjs --phantomjs_cdnurl=https://bitbucket.org/ariya/phantomjs/downloads
165

166
# Or set environment variable
167
PHANTOMJS_CDNURL=https://bitbucket.org/ariya/phantomjs/downloads npm install phantomjs
168
```
169

170
## Platform Support
171

172
- **Supported Platforms**: Linux, macOS (darwin), Windows (win32)
173
- **Supported Architectures**: x64, ia32
174
- **Dependencies**: No runtime dependencies for the public API
175

176
## Important Notes
177

178
- PhantomJS is a separate environment from Node.js - code written for Node.js is not directly compatible
179
- This package is an NPM wrapper, not a Node.js binding to PhantomJS
180
- The PhantomJS binary must be spawned as a child process to execute PhantomJS scripts
181
- The package automatically handles platform-specific binary selection and file permissions