phantomjs
==================
An NPM installer for [PhantomJS](http://phantomjs.org/), headless webkit with JS API.
### DEPRECATED
**Pre-2.0, this package was published to NPM as [phantomjs](https://www.npmjs.com/package/phantomjs).
We changed the name to [phantomjs-prebuilt](https://www.npmjs.com/package/phantomjs-prebuilt) at
the request of PhantomJS team.**
**Please update your package references from `phantomjs` to `phantomjs-prebuilt`**
[![Build Status](https://travis-ci.org/Medium/phantomjs.svg?branch=master)](https://travis-ci.org/Medium/phantomjs)
Building and Installing
-----------------------
```shell
npm install phantomjs
```
Or grab the source and
```shell
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.
Running
-------
```shell
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.
```javascript
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.
Pre-2.0, this package was published to NPM as [phantomjs](https://www.npmjs.com/package/phantomjs).
We changed the name to [phantomjs-prebuilt](https://www.npmjs.com/package/phantomjs-prebuilt) at
the request of PhantomJS team.
Deciding Where To Get PhantomJS
-------------------------------
By default, this package will download phantomjs from our [releases](https://github.com/Medium/phantomjs/releases/).
This should work fine for most people.
##### Downloading from a custom URL
If github is down, or the Great Firewall is blocking github, you may need to use
a different download mirror. To set a mirror, set npm config property `phantomjs_cdnurl`.
Alternatives include `https://bitbucket.org/ariya/phantomjs/downloads` (the official download site)
and `http://cnpmjs.org/downloads`.
```Shell
npm install phantomjs --phantomjs_cdnurl=https://bitbucket.org/ariya/phantomjs/downloads
```
Or add property into your `.npmrc` file (https://www.npmjs.org/doc/files/npmrc.html)
```
phantomjs_cdnurl=https://bitbucket.org/ariya/phantomjs/downloads
```
Another option is to use PATH variable `PHANTOMJS_CDNURL`.
```shell
PHANTOMJS_CDNURL=https://bitbucket.org/ariya/phantomjs/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
```shell
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](https://nodejs.org/api/process.html).
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:
> There is no requirement to install Qt, WebKit, or any other libraries. It
> however still relies on Fontconfig (the package fontconfig or libfontconfig,
> depending on the distribution).
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 github, preventing the installer from downloading the binary.
Try visiting [the download page](https://bitbucket.org/ariya/phantomjs/downloads) 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](https://www.npmjs.org/doc/misc/npm-config.html#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](https://github.com/joyent/node/wiki/Installing-Node.js-via-package-manager#ubuntu-mint-elementary-os)
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.
Contributing
------------
Questions, comments, bug reports, and pull requests are all welcome. Submit them at
[the project on GitHub](https://github.com/Medium/phantomjs/). If you haven't contributed to an
[Medium](http://github.com/Medium/) project before please head over to the
[Open Source Project](https://github.com/Medium/open-source#note-to-external-contributors) 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](https://github.com/dpup)
([personal website](http://pupius.co.uk)) and
[Nick Santos](https://github.com/nicks), supported by
[A Medium Corporation](http://medium.com/).
License
-------
Copyright 2012 [A Medium Corporation](http://medium.com/).
Licensed under the Apache License, Version 2.0.
See the top-level file `LICENSE.txt` and
(http://www.apache.org/licenses/LICENSE-2.0).