PhantomJS Prebuilt

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.

Package Information

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

Core Imports

const phantomjs = require('phantomjs-prebuilt');

For ES6 modules (if using with bundlers that support CommonJS):

import phantomjs from 'phantomjs-prebuilt';

Basic Usage

Programmatic Usage with Node.js

const phantomjs = require('phantomjs-prebuilt');
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 childArgs = [
  path.join(__dirname, 'my-phantom-script.js'),
  'script-argument-1',
  'script-argument-2'
];

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

Command Line Usage

After installation, the phantomjs command is available:

# Run PhantomJS with a script
phantomjs my-script.js

# Run with arguments
phantomjs --load-images=no my-script.js arg1 arg2

# Check PhantomJS version
phantomjs --version

Architecture

PhantomJS Prebuilt is built around several key components designed to handle cross-platform binary distribution and Node.js integration:

• Installation System: Automated download and extraction of platform-specific PhantomJS binaries during npm install, with support for custom CDN mirrors and proxy configurations
• Binary Management: Dynamic path resolution and platform detection system that locates the correct executable based on the target operating system and architecture
• CLI Wrapper: Node.js wrapper script that forwards all arguments and streams to the underlying PhantomJS binary while handling process lifecycle and signal management
• Cross-Platform Support: Automatic detection of Windows, macOS, and Linux platforms with appropriate binary selection and path handling
• PATH Utilities: Helper functions to avoid conflicts with other npm-installed binaries and provide clean environment setup

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.

Capabilities

Binary Path Access

Get the absolute path to the PhantomJS executable for programmatic usage.

/**
 * Path to the PhantomJS binary executable
 * @type {string|null} - Absolute path to binary, null during installation
 */
phantomjs.path

Platform Information

Access platform and architecture information for the installed binary.

/**
 * Target platform identifier for the PhantomJS binary
 * @type {string|undefined} - Platform string (e.g., 'linux', 'darwin', 'win32')
 */
phantomjs.platform

/**
 * Target architecture identifier for the PhantomJS binary  
 * @type {string|undefined} - Architecture string (e.g., 'x64', 'ia32')
 */
phantomjs.arch

Version Information

Get the version of PhantomJS provided by this package.

/**
 * Version of PhantomJS binary provided by this package
 * @type {string} - Version string (currently '2.1.1')
 */
phantomjs.version

PATH Utilities

Utility function for cleaning PATH environment variables to avoid conflicts.

/**
 * Removes node_modules bin directories and ./bin from PATH to avoid conflicts
 * @param {string} path - PATH environment variable string to clean
 * @returns {string} - Cleaned PATH string
 */
phantomjs.cleanPath(path)

Usage Example:

const phantomjs = require('phantomjs-prebuilt');

// Clean PATH to avoid npm-installed phantom conflicts
const cleanedPath = phantomjs.cleanPath(process.env.PATH);
console.log('Original PATH:', process.env.PATH);
console.log('Cleaned PATH:', cleanedPath);

Command Line Interface

The package provides a global phantomjs command that forwards all arguments to the PhantomJS binary.

# Global command available after npm install
phantomjs [phantom-arguments...]

The CLI wrapper handles:

• stdio forwarding: All input/output streams are properly connected
• exit code propagation: Returns the same exit code as PhantomJS
• signal handling: Forwards SIGTERM signals for clean shutdown
• error reporting: Provides clear error messages for execution failures

Installation Configuration

The package supports several environment variables for customizing the installation process:

Custom Download Mirror

# Set custom CDN URL for downloading PhantomJS
PHANTOMJS_CDNURL=https://bitbucket.org/ariya/phantomjs/downloads npm install phantomjs-prebuilt

# Or configure via npm config
npm config set phantomjs_cdnurl https://bitbucket.org/ariya/phantomjs/downloads

Platform Override

# Install for specific platform/architecture
PHANTOMJS_PLATFORM=linux PHANTOMJS_ARCH=x64 npm install phantomjs-prebuilt

Error Handling

Common Installation Issues

ENOENT spawn errors: Usually indicates node or tar not on PATH EPERM permission errors: Insufficient write access or antivirus interference
ECONNRESET network errors: Download failures, try custom CDN URL

Runtime Error Detection

const phantomjs = require('phantomjs-prebuilt');
const childProcess = require('child_process');

if (!phantomjs.path) {
  console.error('PhantomJS binary not available (still installing?)');
  process.exit(1);
}

const child = childProcess.execFile(phantomjs.path, ['--version'], (err, stdout, stderr) => {
  if (err) {
    console.error('Failed to execute PhantomJS:', err.message);
    return;
  }
  console.log('PhantomJS version:', stdout.trim());
});

child.on('error', (err) => {
  console.error('PhantomJS process error:', err);
});

Cross-Platform Considerations

• Automatic platform detection: Downloads appropriate binary for current OS/architecture
• Repository rebuilding: Run npm rebuild when working across different platforms
• Manual binary detection: Automatically uses existing PhantomJS on PATH for non-global installs
• Platform-specific paths: Binary executable names vary by platform (.exe on Windows)

Types

/**
 * Main module exports object
 */
interface PhantomJSModule {
  /** Path to PhantomJS binary, null during installation */
  path: string | null;
  /** Platform identifier for installed binary */
  platform?: string;
  /** Architecture identifier for installed binary */
  arch?: string;
  /** PhantomJS version provided by this package */
  version: string;
  /** Utility to clean PATH environment variable */
  cleanPath(path: string): string;
}