phantomjs

An NPM installer for PhantomJS, headless webkit with JS API.

Building and Installing

npm install phantomjs

Or grab the source and

node ./install.js

What this installer is really doing is just grabbing a particular "blessed" (by this module) version of Phantom. As new versions of Phantom are released and vetted, this module will be updated accordingly.

The package has been set up to fetch and run Phantom for MacOS (darwin), Linux based platforms (as identified by nodejs), and -- as of version 0.2.0 -- Windows (thanks to Domenic Denicola). If you spot any platform weirdnesses, let us know or send a patch.

Running

bin/phantomjs [phantom arguments]

And npm will install a link to the binary in node_modules/.bin as it is wont to do.

Running via node

The package exports a path string that contains the path to the phantomjs binary/executable.

Below is an example of using this package via node.

var path = require('path')
var childProcess = require('child_process')
var phantomjs = require('phantomjs')
var binPath = phantomjs.path

var childArgs = [
  path.join(__dirname, 'phantomjs-script.js'),
  'some other argument (passed to phantomjs script)'
]

childProcess.execFile(binPath, childArgs, function(err, stdout, stderr) {
  // handle results
})

Versioning

The major and minor number tracks the version of PhantomJS that will be installed. The patch number is incremented when there is either an installer update or a patch build of the phantom binary.

Deciding Where To Get PhantomJS

By default, this package will download phantomjs from https://bitbucket.org/ariya/phantomjs/downloads. This should work fine for most people.

Downloading from a custom URL

If bitbucket is down, or the Great Firewall is blocking bitbucket, you may need to use a download mirror. To set a mirror, set npm config property phantomjs_cdnurl. Default is ``.

npm install phantomjs --phantomjs_cdnurl=http://cnpmjs.org/downloads

Or add property into your .npmrc file (https://www.npmjs.org/doc/files/npmrc.html)

phantomjs_cdnurl=http://cnpmjs.org/downloads

Another option is to use PATH variable PHANTOMJS_CDNURL.

PHANTOMJS_CDNURL=http://cnpmjs.org/downloads npm install phantomjs

Using PhantomJS from disk

If you plan to install phantomjs many times on a single machine, you can install the phantomjs binary on PATH. The installer will automatically detect and use that for non-global installs.

Cross-Platform Repositories

PhantomJS needs to be compiled separately for each platform. This installer finds a prebuilt binary for your operating system, and downloads it.

If you check your dependencies into git, and work on a cross-platform team, then you need to tell NPM to rebuild any platform-specific dependencies. Run

npm rebuild

as part of your build process. This problem is not specific to PhantomJS, and this solution will work for any NodeJS package with native or platform-specific code.

If you know in advance that you want to install PhantomJS for a specific architecture, you can set the environment variables: PHANTOMJS_PLATFORM (to set target platform) and PHANTOMJS_ARCH (to set target arch), where platform and arch are valid values for process.platform and process.arch.

A Note on PhantomJS

PhantomJS is not a library for NodeJS. It's a separate environment and code written for node is unlikely to be compatible. In particular PhantomJS does not expose a Common JS package loader.

This is an NPM wrapper and can be used to conveniently make Phantom available It is not a Node JS wrapper.

I have had reasonable experiences writing standalone Phantom scripts which I then drive from within a node program by spawning phantom in a child process.

Read the PhantomJS FAQ for more details: http://phantomjs.org/faq.html

Linux Note

An extra note on Linux usage, from the PhantomJS download page:

This package is built on CentOS 5.8. It should run successfully on Lucid or more modern systems (including other distributions). There is no requirement to install Qt, WebKit, or any other libraries. It is however expected that some base libraries necessary for rendering (FreeType, Fontconfig) and the basic font files are available in the system.

Troubleshooting

Installation fails with spawn ENOENT

This is NPM's way of telling you that it was not able to start a process. It usually means:

• node is not on your PATH, or otherwise not correctly installed.
• tar is not on your PATH. This package expects tar on your PATH on Linux-based platforms.

Check your specific error message for more information.

Installation fails with Error: EPERM or operation not permitted or permission denied

This error means that NPM was not able to install phantomjs to the file system. There are three major reasons why this could happen:

• You don't have write access to the installation directory.
• The permissions in the NPM cache got messed up, and you need to run npm cache clean to fix them.
• You have over-zealous anti-virus software installed, and it's blocking file system writes.

Installation fails with Error: read ECONNRESET or Error: connect ETIMEDOUT

This error means that something went wrong with your internet connection, and the installer was not able to download the PhantomJS binary for your platform. Please try again.

I tried again, but I get ECONNRESET or ETIMEDOUT consistently.

Do you live in China, or a country with an authoritarian government? We've seen problems where the GFW or local ISP blocks bitbucket, preventing the installer from downloading the binary.

Try visiting the the download page manually. If that page is blocked, you can try using a different CDN with the PHANTOMJS_CDNURL env variable described above.

I am behind a corporate proxy that uses self-signed SSL certificates to intercept encrypted traffic.

You can tell NPM and the PhantomJS installer to skip validation of ssl keys with NPM's strict-ssl setting:

npm set strict-ssl false

WARNING: Turning off strict-ssl leaves you vulnerable to attackers reading your encrypted traffic, so run this at your own risk!

I tried everything, but my network is b0rked. What do I do?

If you install PhantomJS manually, and put it on PATH, the installer will try to use the manually-installed binaries.

I'm on Debian or Ubuntu, and the installer failed because it couldn't find node

Some Linux distros tried to rename node to nodejs due to a package conflict. This is a non-portable change, and we do not try to support this. The official documentation recommends that you run apt-get install nodejs-legacy to symlink node to nodejs on those platforms, or many NodeJS programs won't work properly.

The latest version of this package installs PhantomJS 1.9.8. When is PhantomJS 2.0 coming?

In January 2015, the PhantomJS project released PhantomJS 2.0 with statically compiled Windows binaries.

They were not able to create statically-compiled binaries for Linux or OSX 9+.

This put us in a difficult position. The whole reason this NPM installer exists is to provide a portable, cross-platform installation process for PhantomJS. Without static binaries, we can't support PhantomJS 2.0.

If you work on a project that does not need cross-platform installation (for example, if your users can compile and install phantomjs themselves on PATH), then there is no good reason to depend on this package. You should call phantomjs directly with child_process.spawn.

The core PhantomJS team is hard at work trying to producing static binaries, but there's currently no timeline.

Contributing

Questions, comments, bug reports, and pull requests are all welcome. Submit them at the project on GitHub. If you haven't contributed to an Medium project before please head over to the Open Source Project and fill out an OCLA (it should be pretty painless).

Bug reports that include steps-to-reproduce (including code) are the best. Even better, make them in the form of pull requests.

Author

Dan Pupius (personal website) and Nick Santos, supported by A Medium Corporation.

License

Copyright 2012 A Medium Corporation.

Licensed under the Apache License, Version 2.0. See the top-level file LICENSE.txt and (http://www.apache.org/licenses/LICENSE-2.0).