node package manager


HTML Pages

Simple development http server for file serving and directory listing made by a Designer. Use it for hacking your HTML/JavaScript/CSS files, but not for deploying your final site.
Visit HTML Pages »

Table of contents


npm version npm module downloads per month node JavaScript Style Guide Linux and Mac Build Status Windows Build Status dependency Status devDependency Status

Quick start

Each of us already wanted to share a certain directory on our network by running just a command little command, Am I right? Then this module is exactly what you're looking for: It provides a beautiful interface for listing the directory's contents and switching into sub folders.

In addition, it's also awesome because it comes to serving static sites. If a directory contains an index.html, html-pages will automatically render it instead of serving directory contents, and will serve any .html file as a rendered page instead of file's content as plaintext.

Another huge reason to use this package is that AJAX requests don't work with the file:// protocol due to security restrictions, i.e. you need a server if your site fetches content through JavaScript.


You need to have node.js (>v.6.6.0) and npm installed. You should probably install this globally.

Npm way

npm install -g html-pages

This will install html-pages globally so that it may be run from the command line.

Manual way

git clone
cd html-pages
npm install # Local dependencies if you want to hack
npm install -g # Install globally

Usage from command line

You just have to call the command html-pages in your project's directory. Alternatively you can add the path to be a command line parameter.

Command line parameters

Run this command to see a list of all available options:

html-pages --help
  • -a, --auth — Enables http-auth using the PAGES_USER and PAGES_PASSWORD environment variables
  • -b, --browser string — Specify browser to use instead of system default
  • -c, --cache number — Time in milliseconds for caching files in the browser (defaults to 3600)
  • -C, --cors — Setup CORS headers to allow requests from any origin
  • -d, --directory-index file — The index file of a directory. Set to empty "" to always show the directory listing (defaults to index.html)
  • -h, --help — Output usage information
  • -i, --ignore string/array — Files and directories to ignore. Use a string (comma-separated string for paths to ignore) if your are using the command line and an array if you are calling it via API
  • --no-browser — Suppress automatic web browser launching
  • --no-cache — Disabled the caching files in the browser
  • --no-clipboard — Don't copy address to clipboard
  • --no-listing — Turn off the directory listings
  • --no-notifications — Suppress automatic notifications launching
  • --no-port-scan — Disabled the port scanning when the selected port is already in use
  • -p, --port number — Port to listen on (defaults to 8084)
  • -r, --root string — The root directory (defaults to ./)
  • -s, --silent — Don't log anything to the console
  • -u, --unzipped — Disable GZIP compression
  • -v, --version — Output the version number

Default options:

If a file ~/.html-pages.json exists it will be loaded and used as default options for html-pages on the command line. See Options for option names.


If you set the --auth flag, this package will look for a username and password in the PAGES_USER and PAGES_PASSWORD environment variables.

As an example, this is how such a command could look like:

PAGES_USER=daniel PAGES_PASSWORD=1904 html-pages --auth

Usage from node

You can also use the package inside your application. Just load it:

const pages = require('html-pages')

And call it with flags (check Command line parameters for the full list):

const pagesServer = pages(__dirname, {
  port: 1904,
  'directory-index': '',
  'no-clipboard': true,
  ignore: ['.git', 'node_modules']

To stop the server just use the method:


What next?

  • Display logs;
  • Enable HTTPS support;
  • Add Proxy support;
  • Provide a /robots.txt (whose content defaults to 'User-agent: *\nDisallow: /');
  • Improve HTML errors;
  • Add grid layout;

Version history

  • v1.5.0
    • Using Travis CI (Linux and Mac Build Status)
    • Using AppVeyor (Windows Build Status)
    • CORS support
    • Load initial settings from ~/.html-pages.json if exists
    • Minor improvements
    • Improve tests
  • v1.4.0
    • Update dependencies
  • v1.3.0
    • Code Refactoring
  • v1.2.0
    • Add web browser launching support:
      • it uses opn to allow opening links in different browsers;
    • Minor improvements
  • v1.1.0
    • Add icons with the file types to the directory listing;
    • Add example files;
  • v1.0.0
    • Initial release


Daniel Cardoso (@DanielCardoso) -