Quickly start a server to preview the assets of any directory!
$ npm install --save sirv-cli
Note: This module can also be installed and used globally~!
PORTenvironment variables will override the
$ 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
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
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.
--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.
Note: Requires Node.js v8.4.0 or later.
--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
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.singlefor 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
# 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
sirv-cli for production file-serving, you should:
--devis not used
- Enable HTTP/2 (
--http2) with valid key and cert
- Precompile brotli and/or gzip file variants
For maximum performance, you should also use
--quiet to disable the I/O from logging.
sirv-cliis 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.
MIT © Luke Edwards