Quickly start a server to preview the assets of any directory!

Install

$ npm install --save sirv-cli

Note: This module can also be installed and used globally~!

Usage

Important: The HOST and PORT environment variables will override the --host and --port flags, respectively.

$ sirv --help

  Description
    Run a static file server

  Usage
    $ sirv [dir] [options]

  Options
    -D, --dev          Enable "dev" mode
    -e, --etag         Enable "ETag" header
    -d, --dotfiles     Enable dotfile asset requests
    -c, --cors         Enable "CORS" headers to allow any origin requestor
    -G, --gzip         Send precompiled "*.gz" files when "gzip" is supported  (default true)
    -B, --brotli       Send precompiled "*.br" files when "brotli" is supported  (default true)
    -m, --maxage       Enable "Cache-Control" header & define its "max-age" value (sec)
    -i, --immutable    Enable the "immutable" directive for "Cache-Control" header
    -k, --http2        Enable the HTTP/2 protocol. Requires Node.js 8.4.0+
    -C, --cert         Path to certificate file for HTTP/2 server
    -K, --key          Path to certificate key for HTTP/2 server
    -P, --pass         Passphrase to decrypt a certificate key
    -s, --single       Serve as single-page application with "index.html" fallback
    -I, --ignores      Any URL pattern(s) to ignore "index.html" assumptions
    -q, --quiet        Disable logging to terminal
    -H, --host         Hostname to bind  (default localhost)
    -p, --port         Port to bind  (default 5000)
    -v, --version      Displays current version
    -h, --help         Displays this message

  Examples
    $ sirv build --cors --port 8080
    $ sirv public --quiet --etag --maxage 31536000 --immutable
    $ sirv public --http2 --key priv.pem --cert cert.pem
    $ sirv public -qeim 31536000
    $ sirv --port 8080 --etag
    $ sirv --host --dev

Network Access

For security reasons, sirv-cli does not expose your server to the network by default. This means that your machine, and only your machine, will be able to access the localhost server.

If, however, your coworker wants to access the server from their computer, or you want to preview your work on a mobile device, you must use the --host flag. Only then will your server be accessible to other devices on the same network.

Using --host without a value is equivalent to --host 0.0.0.0, which is makes it discoverable publicly. You may customize this by passing a different value – but you probably don't need to!

Important: Only the Network: address is accessible to others. The Local: address is still private to you.

HTTP/2

Note: Requires Node.js v8.4.0 or later.

The --key and --cert flags are required since no browsers support unencrypted HTTP/2.These must be valid file paths (resolved from process.cwd()), which are read and passed into http2.createSecureServer.

You can generate a certificate and key for local development quickly with:

$ openssl req -x509 -newkey rsa:2048 -nodes -sha256 -subj '/CN=localhost' \
  -keyout localhost-key.pem -out localhost-cert.pem

# Now we can run a HTTP/2 server
$ sirv --http2 --key localhost-key.pem --cert localhost-cert.pem

To bypass the "third party verification" error page, you may use mkcert to generate a locally-trusted development certificate:

$ mkcert -install
$ mkcert -key-file localhost-key.pem -cert-file localhost-cert.pem localhost 127.0.0.1

# Now we can run a HTTP/2 server with verified SSL
$ sirv --http2 --key localhost-key.pem --cert localhost-cert.pem

Single Page Applications

You must pass the --single flag to enable single-page application ("SPA") mode. This will, for example, serve your directory's index.html file when an unknown path (eg; /foo/bar) does not resolve to another page.

Note: Please refer to opts.single for the lookup sequence.

Any asset requests (URLs that end with an extension) ignore --single behavior and will send a 404 response instead of the "index.html" fallback. To ignore additional paths, pass URL patterns to the --ignores argument.

# Don't include "/blog*" or "/portfolio*" pages into SPA
$ sirv public --single --ignores "^/blog" --ignores "^/portfolio"

You may pass a string to customize which file should be sent as fallback.In other words, --single shell.html will send the directory's shell.html file instead of its index.html file.

Production

When using sirv-cli for production file-serving, you should:

1. Ensure --dev is not used
2. Enable HTTP/2 (--http2) with valid key and cert
3. Precompile brotli and/or gzip file variants
4. Enable --gzip and/or --brotli flags

For maximum performance, you should also use --quiet to disable the I/O from logging.

Notice: While sirv-cli is certainly "production ready", using a CDN in production is always recommended. Especially when performance is a concern, there are much better solutions than using Node.js as a file server. Most everything has HTTP/2 and "SPA" support nowadays – consider NGINX or h2o.

License

MIT © Luke Edwards