hostlocal

Serve files from a directory over HTTP/1.1 and HTTP/2, with live reload notifications over a websocket. It will automatically create self-signed certificates.

This server is quite opinionated about its defaults to make setup as easy as possible... if you have a problem shaped like mine.

NOTE:

This server is NOT intended for production use, or any other place where the clients are not fully-trusted. Simplifying assumptions have been made to optimize code size, performance, and usability that make its use in a production context inappropriate. Security issues that are filed that do not take this note into account will not be prioritized.

Run

# Serve the docs directory, and open index.html in your default browser.
npx hostlocal docs

CLI

Usage: hostlocal [options] [directory]

Arguments:
  directory                   Directory to serve. (default: cwd)

Options:
  -6, --ipv6                  Listen on IPv6 only, if host supports both IPv4
                              and IPv6.
  -c, --config <file>         If the given file exists, import it as a module
                              and use its default export as the options.  Name
                              is relative to cwd. Command line parameters
                              overwrite options from the config file. (default:
                              ".hostlocal.js")
  --certDir <directory>       Directory, relative to cwd, to cache cert info.
                              (default: ".cert")
  -e, --exec <shell command>  Execute this command when the glob changes.
                              (default: "npm run build")
  -g, --glob <pattern>        Set of files to watch.  If one of these changes,
                              execute the command in the --exec option.  Can be
                              specified multiple times.
  -h, --help                  display help for command
  -H, --host <address>        Hostname or IP address to listen on. "::" for
                              everything. (default: "localhost")
  -i, --initial               If glob is specified, run the exec command on
                              startup, before listening.
  --logFile <file>            If specified, JSON logs are written to this file.
  --no-script                 If specified, JavScript will not be added to the
                              end of HTML files to do auto-refresh.
  --notAfterDays <number>     How many days is the certificate valid? (default:
                              7)
  -o, --open <path>           Open this path in the default browser.  Relative
                              to server root and prefix, if specified.  If
                              empty (""), do not open anything. (default: ".")
  -O, --no-open               Do not open a page in the default browser.
  -p, --port <number>         Port to serve content from.  Use 0 to get an
                              unused port. (default: 8111)
  -P, --prefix <string>       Make all of the URLs served have paths that start
                              with this prefix, followed by a slash.
  -q, --quiet                 Do less logging.  Can be specified more than
                              once.
  --rawMarkdown               Do not process markdown into HTML.
  -t, --timeout <number>      Time, in ms, to allow exec to run.
  -v, --verbose               Do more logging.  Can be specified more than
                              once.
  -V, --version               output the version number

Config files

Instead of using the command line, you can store your configuration in a file, by default called ".hostlocal.js". This is an ES6 module with a default export containing your config. Its default value is:

/**
 * @type {import('./lib/index.js').HostOptions}
 */
export default {
  certDir: '.cert',
  config: '.hostlocal.js',
  dir: process.cwd(),
  exec: 'npm run build',
  CGI: {},
  glob: [],
  headers: {},
  host: 'localhost',
  index: ['index.html', 'index.htm', 'README.md'],
  initial: false,
  ipv6: false,
  logLevel: 0,
  logFile: null,
  notAfterDays: 7,
  open: '.',
  port: 8111,
  prefix: '',
  rawMarkdown: false,
  script: true,
  signal: null,
  timeout: null,
};

Command-line options take precedence over these. Most of these match their command line options for semantics. Others:

• dir: Serve this directory (tied to optional directory in CLI).
• CGI: Object containing a map from original mime type to command. The command is any shell command that emits at least a content-type header with string CR/LF in the header. NOTE: This feature has a high probability of generating a security issue when you misconfigure it and allow external access. This is an example that might work sometimes, but would be catastrophic with untrusted inputs:

{
  "CGI": {
    "application/x-httpd-php": "php-cgi",
  }
}

• index: Array of strings for files to search for if a directory is requested.
• logLevel: The sum of the number of -v options (+1 each) an -q options (-1 each). -3: fatal, -2: error, -1: warn, 0: info, 1: debug, 2: trace.
• open: Specify "" or false to not open a file in the default browser.
• script: The opposite of the --no-script CLI option.
• signal: An abort signal that can be used to shut down the server as cleanly as possible.

API

Full API documentation is available.

Example:

import {hostLocal} from 'hostlocal';

const server = await hostLocal({port: 8111});
server.on('listen', baseURL => console.log(baseURL.toString()));
await server.start();