The optimized & lightweight middleware for serving requests to static assets
The sirv npm package is a simple, high-performance, single-purpose HTTP server for serving static files. It is designed to be fast and efficient, making it ideal for serving the static assets of web applications.
Serving static files
This code sample demonstrates how to use sirv with Polka (a lightweight web server) to serve static files from the 'public' directory.
const sirv = require('sirv');
const polka = require('polka');
const server = polka();
server.use(sirv('public'));
server.listen(3000, err => {
if (err) throw err;
console.log('> Running on localhost:3000');
});Customizing options
This code sample shows how to customize sirv with options such as cache control headers and enabling single-page application (SPA) mode.
const sirv = require('sirv');
const options = {
maxAge: 31536000, // 1 year in seconds
immutable: true,
etag: true,
single: true
};
const serve = sirv('public', options);Using with middleware
This code sample illustrates how to use sirv as middleware in an Express application to serve static files with development options enabled.
const sirv = require('sirv');
const express = require('express');
const app = express();
app.use(sirv('public', { dev: true }));
app.listen(3000, () => console.log('Server running on port 3000'));Express' built-in middleware function to serve static files. It is part of the Express.js framework and is widely used for serving static assets. Compared to sirv, it is more feature-rich but also heavier due to being part of a larger framework.
A Node.js middleware for serving static files that is compatible with many frameworks like Express. It is similar to sirv but offers more configuration options and is part of the larger Express ecosystem.
A static file serving middleware for Koa, which is another web framework for Node.js. Koa-static is designed to work within the Koa ecosystem and provides a similar feature set to sirv but is tailored for Koa's middleware pattern.
The optimized and lightweight middleware for serving requests to static assets
You may use sirv as a very fast and lightweight alternative to serve-static.
The massive performance advantage over serve-static is explained by not relying on the file system for existence checks on every request. These are expensive interactions and must be avoided whenever possible! Instead, when not in "dev" mode, sirv performs all its file-system operations upfront and then relies on its cache for future operations.
This middleware will work out of the box for Polka, Express, and other Express-like frameworks. It will also work with the native http, https and http2 modules. It requires very little effort to modify/wrap it for servers that don't accept the (req, res, next) signature.
:bulb: For a feature-complete CLI application, check out the sibling sirv-cli package as an alternative to zeit/serve~!
$ npm install --save sirv
const sirv = require('sirv');
const polka = require('polka');
const compress = require('compression')();
// Init `sirv` handler
const assets = sirv('public', {
maxAge: 31536000, // 1Y
immutable: true
});
polka()
.use(compress, assets)
.use('/api', require('./api'))
.listen(3000, err => {
if (err) throw err;
console.log('> Ready on localhost:3000~!');
});
Returns: Function
The returned function is a middleware in the standard Express-like signature: (req, res, next), where req is the http.IncomingMessage, res is the http.ServerResponse, and next (in this case) is the function to call if no file was found for the given path.
When defined, a next() callback is always called instead of the opts.onNoMatch callback. However, unlike onNoMatch, your next() is given no arguments.
Type: String
Default: .
The directory from which to read and serve assets. It is resolved to an absolute path — you must provide an absolute path yourself if process.cwd() is not the correct assumption.
Type: Boolean
Default: false
Enable "dev" mode, which disables/skips caching. Instead, sirv will traverse the file system on every request.
Additionally, dev mode will ignore maxAge and immutable as these options generate a production-oriented Cache-Control header value.
Important: Do not use
devmode in production!
Type: Boolean
Default: false
Generate and attach an ETag header to responses.
Note: If an incoming request's
If-None-Matchheader matches theETagvalue, a304response is given.
Type: Boolean
Default: false
Allow requests to dotfiles (files or directories beginning with a .).
Note: Requests to
/.well-known/*are always allowed.
Type: Array<String>
Default: ['html', 'htm']
The file extension fallbacks to check for if a pathame is not initially found. For example, if a /login request cannot find a login filename, it will then look for login.html and login.htm before giving up~!
Important: Actually,
sirvwill also look forlogin/index.htmlandlogin/index.htmbefore giving up.
Type: Boolean
Default: false
Determine if sirv look for precompiled *.gz files.
Must be enabled and the incoming request's Accept Encoding must include "gzip" in order for sirv to search for the gzip'd alternative.
Note: The
.gzassumption also applies to theopts.extensionslist.
// NOTE: PSEUDO CODE
// Showing lookup logic
// Request: [Accept-Encoding: gzip] "/foobar.jpg"
lookup([
'/foobar.jpg.gz', '/foobar.jpg',
'/foobar.jpg.html.gz', '/foobar.jpg/index.html.gz',
'/foobar.jpg.htm.gz', '/foobar.jpg/index.htm.gz',
'/foobar.jpg.html', '/foobar.jpg/index.html',
'/foobar.jpg.htm', '/foobar.jpg/index.htm',
]);
// Request: [Accept-Encoding: gzip] "/"
lookup([
'/index.html.gz',
'/index.htm.gz',
'/index.html',
'/index.htm',
]);
Type: Boolean
Default: false
Determine if sirv look for precompiled *.br files.
Must be enabled and the incoming request's Accept Encoding must include either "br" or "brotli" in order for sirv to search for the brotli-compressed alternative.
Note: The
.brassumption also applies to theopts.extensionslist.
When both opts.broli and opts.gzip are enabled — and all conditions are equal — then the brotli variant always takes priority.
// NOTE: PSEUDO CODE
// Showing lookup logic
// Request: [Accept-Encoding: br] "/foobar.jpg"
lookup([
'/foobar.jpg.br', '/foobar.jpg',
'/foobar.jpg.html.br', '/foobar.jpg/index.html.br',
'/foobar.jpg.htm.br', '/foobar.jpg/index.htm.br',
'/foobar.jpg.html', '/foobar.jpg/index.html',
'/foobar.jpg.htm', '/foobar.jpg/index.htm',
]);
// Request: [Accept-Encoding: br,gz] "/"
lookup([
'/index.html.br'
'/index.htm.br'
'/index.html.gz'
'/index.htm.gz'
'/index.html'
'/index.htm'
]);
Type: Number
Default: undefined
Enables the Cache-Control header on responses and sets the max-age value (in seconds).
For example, maxAge: 31536000 is equivalent to one year.
Type: Boolean
Default: false
Appends the immutable directive on your Cache-Control header, used for uniquely-named assets that will not change!
Important: Will only work if
opts.maxAgehas a value defined!
Type: Boolean or String
Default: false
Treat the directory as a single-page application.
When true, the directory's index page (default index.html) will be sent if the request asset does not exist.
You may pass a string value to use a file instead of index.html as your fallback.
For example, if "/about" is requested but no variants of that file exist, then the response for "/" is sent instead:
// Note: This is psuedo code to illustrate what's happening
// Request: "/about"
let file = find(['/about', '/about.html', '/about.htm', '/about/index.html', '/about.htm']);
if (file) {
send(file);
} else if (opts.single === true) {
file = find(['/', '/index.html', '/index.htm']);
send(file);
} else if (typeof opts.single === 'string') {
file = find([opts.single]);
send(file);
} else {
// next() or 404
}
Type: false or Array<String | RegExp>
Specify paths/patterns that should ignore the fallback behavior that opts.single provides.
By default, any asset-like path (URLs that end with an extension) will be ignored. This means that, for example, if /foobar.jpg is not found, a 404 response is sent instead of the index.html fallback.
Additionally, any /.well-known/* pathname ignores the fallback – as do all other dotfile requests when opts.dotfiles is enabled.
Any string value(s) will be passed through new RegExp(value, 'i') directly.
Finally, you may set ignores: false to disable all ignores, including the defaults. Put differently, this will fallback all unknown pathnames to your index.html (or custom opts.single value).
Important: Only has an effect if
opts.singleis enabled.
Type: Function
A custom function to run if a file cannot be found for a given request.
By default, sirv will send a basic (404) Not found response.
The function receives the current req <IncomingMessage>, res <ServerResponse> pair for as its two arguments.
Note: This won't run if a
nextcallback has been provided to the middleware; seesirvdescription.
Type: Function
A custom function to append or change any headers on the outgoing response. There is no default.
Its signature is (res, pathname, stats), where res is the ServerResponse, pathname is incoming request path (stripped of queries), and stats is the file's result from fs.statSync.
MIT © Luke Edwards
FAQs
The optimized & lightweight middleware for serving requests to static assets
The npm package sirv receives a total of 7,127,997 weekly downloads. As such, sirv popularity was classified as popular.
We found that sirv demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
PyPI confirms no security flaws were exploited in the Ultralytics supply chain attack and highlights improvements for safer package publishing.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.