PhantomJS

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.

Package Information

• Package Name: phantomjs
• Package Type: npm
• Language: JavaScript (Node.js)
• Installation: npm install phantomjs

Core Imports

const phantomjs = require('phantomjs');

For ES modules (if supported in your environment):

import phantomjs from 'phantomjs';

Basic Usage

const phantomjs = require('phantomjs');
const childProcess = require('child_process');
const path = require('path');

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

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

childProcess.execFile(binPath, childArgs, function(err, stdout, stderr) {
  if (err) {
    console.error('PhantomJS execution failed:', err);
    return;
  }
  console.log('PhantomJS output:', stdout);
});

Capabilities

Binary Path Access

Provides the absolute path to the installed PhantomJS binary executable.

/**
 * Absolute path to the PhantomJS binary executable.
 * Returns null if the binary is not yet installed (e.g., during installation).
 */
phantomjs.path; // {string|null}

Platform Information

Provides information about the target platform and architecture.

/**
 * Target platform identifier (e.g., 'linux', 'darwin', 'win32').
 * May be undefined if location module fails to load during installation.
 */
phantomjs.platform; // {string|undefined}

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

Version Information

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

/**
 * Version string of the PhantomJS binary installed by this package.
 * Note: This is the PhantomJS binary version (e.g., '1.9.8'), 
 * which may differ from the npm package version.
 */
phantomjs.version; // {string}

PATH Utilities

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

/**
 * Removes node_modules and ./bin entries from a PATH string to avoid
 * conflicts with npm-installed binaries.
 * @param {string} path - PATH environment variable string  
 * @returns {string} Cleaned PATH string
 */
phantomjs.cleanPath(path);

Usage Example:

const phantomjs = require('phantomjs');

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

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

// Use cleaned PATH to avoid finding npm-installed binaries
process.env.PATH = cleanedPath;

Command Line Interface

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

# Direct execution via npm bin linking
phantomjs --version
phantomjs script.js arg1 arg2

# Or via npx
npx phantomjs --version

Architecture

The phantomjs package consists of several key components:

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

Error Handling

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

Configuration

The package supports several environment variables and npm configuration options:

• PHANTOMJS_CDNURL: Override the download CDN URL
• PHANTOMJS_PLATFORM: Override target platform detection
• PHANTOMJS_ARCH: Override target architecture detection
• npm config phantomjs_cdnurl: Set CDN URL via npm config

Example:

# Install with custom CDN
npm install phantomjs --phantomjs_cdnurl=https://bitbucket.org/ariya/phantomjs/downloads

# Or set environment variable
PHANTOMJS_CDNURL=https://bitbucket.org/ariya/phantomjs/downloads npm install phantomjs

Platform Support

• Supported Platforms: Linux, macOS (darwin), Windows (win32)
• Supported Architectures: x64, ia32
• Dependencies: No runtime dependencies for the public API

Important Notes

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