Sirv Static File Server Middleware

Common errors

• ERR_REQUIRE_ESM: require() of ES Module ... sirv/index.mjs not supported.

  cause Attempting to `require('sirv')` in a Node.js environment configured for ES Modules (`"type": "module"` in `package.json`) after upgrading to sirv v3+.
  fix Change `const sirv = require('sirv');` to `import sirv from 'sirv';` and ensure your project uses ES Modules correctly.

• GET /path/to/asset 404 Not Found

  cause The `dir` option provided to `sirv()` is incorrect, or the requested file does not exist within that directory, or `opts.dotfiles` and `opts.extensions` are not configured to match the asset.
  fix Verify the `dir` path is absolute and correct. Check if `opts.dotfiles` is `true` for dotfiles, and `opts.extensions` includes the necessary fallback extensions (e.g., `['html']` for `/foo` to find `/foo.html`). Also, ensure file permissions allow Node.js to read the files.

• Error: Port 3000 is already in use

  cause Another process is already listening on the port that your `polka` (or other HTTP server) instance is trying to bind to.
  fix Change the `PORT` variable in your quickstart code to an unused port (e.g., 8080, 5000) or ensure the conflicting process is stopped. You can also use a tool like `lsof -i :<PORT>` on Unix-like systems to identify the process.

Warnings

• breaking Sirv v3.0.0 and later require Node.js version 18 or higher. Projects running on older Node.js versions must either upgrade Node.js or remain on sirv v2.x.
  Fix: Upgrade Node.js to version 18 or higher (e.g., using nvm) or pin sirv to a 2.x version in your `package.json` (e.g., `"sirv": "^2.0.0"`).
• breaking Sirv v3.0.0 introduced native ESM support via an `exports` map, which changes how the package is imported. Direct `require()` statements in ESM contexts or projects with `"type": "module"` in `package.json` may break, resulting in `ERR_REQUIRE_ESM`.
  Fix: Migrate your imports to use ESM syntax: `import sirv from 'sirv';`. Ensure your project is configured for ESM, typically by setting `"type": "module"` in `package.json` or using `.mjs` file extensions.
• gotcha Using `opts.dev: true` enables 'dev' mode, which disables file caching and performs file system checks on every request. This is highly inefficient and should *never* be used in production environments, as it will severely degrade performance.
  Fix: Ensure `opts.dev` is set to `false` or omitted (default is `false`) for production builds. A common pattern is `dev: process.env.NODE_ENV === 'development'`.
• gotcha The `dir` option in `sirv(dir, opts)` expects a directory path. While it resolves relative paths based on `process.cwd()`, relying on `process.cwd()` can be brittle in complex deployment scenarios. Incorrect paths can lead to assets not being found.
  Fix: Always provide an absolute path for `dir`, e.g., using `path.resolve(__dirname, 'public')` or `path.join(path.dirname(fileURLToPath(import.meta.url)), 'public')` for ESM.
• gotcha Sirv v3.0.2 includes a patch to prevent serving top-level files that unexpectedly share a name with the configured static directory. If you previously relied on such a pattern for some edge cases, this behavior will now be prevented.
  Fix: Ensure your file structure does not have top-level files named identically to your static asset directory (e.g., if `dir` is 'public', do not have a file named 'public' in the root serving directory).

Install

• npm install sirv npm
• yarn add sirv yarn
• pnpm add sirv pnpm

Imports

• sirv
  wrong:

  const sirv = require('sirv');

  correct:

  import sirv from 'sirv';

  Since v3.0.0, sirv is primarily designed for ESM usage and requires Node.js 18+. While CJS might still work in some setups, native ESM import is the recommended and type-correct way. Using `require` with `type: module` in `package.json` will result in an error.
• SirvMiddlewareFunction

  import type { SirvOptions } from 'sirv';

  TypeScript type for SirvOptions, useful for explicit type annotations when configuring the middleware.
• sirv

  import sirv from 'sirv';

  The default export is the `sirv` factory function itself, which returns the middleware. There are no other named exports typically used directly by consumers.

Quickstart

This quickstart demonstrates how to set up `sirv` with `polka` and `compression` to serve static files from a 'public' directory. It highlights ESM usage, configuration options like `maxAge` and `dev` mode, and shows how to integrate it alongside other middleware. It dynamically creates a 'public' directory and files for immediate execution.

import polka from 'polka';
import sirv from 'sirv';
import compression from 'compression';
import * as path from 'node:path';
import { fileURLToPath } from 'node:url';

const __dirname = path.dirname(fileURLToPath(import.meta.url));
const publicDir = path.join(__dirname, 'public');

// Create a dummy 'public' directory and an index.html file for demonstration
import { promises as fs } from 'node:fs';
async function setupPublicDir() {
  await fs.mkdir(publicDir, { recursive: true });
  await fs.writeFile(path.join(publicDir, 'index.html'), '<h1>Hello from Sirv!</h1><p>This is a static file.</p>');
  await fs.writeFile(path.join(publicDir, 'styles.css'), 'body { font-family: sans-serif; background-color: #f0f0f0; }');
}

// Initialize sirv handler
const assets = sirv(publicDir, {
  maxAge: 31536000, // 1 year
  immutable: true,
  gzip: true, // Look for precompiled .gz files
  dotfiles: false, // Don't serve dotfiles
  dev: process.env.NODE_ENV === 'development' // Enable dev mode for caching control
});

const PORT = process.env.PORT ?? 3000;

await setupPublicDir();

polka()
  .use(compression()) // Apply compression before sirv
  .use(assets) // Serve static assets
  .use('/api', (req, res) => {
    res.setHeader('Content-Type', 'application/json');
    res.end(JSON.stringify({ message: 'This is an API endpoint', timestamp: Date.now() }));
  })
  .listen(PORT, (err) => {
    if (err) throw err;
    console.log(`> Ready on http://localhost:${PORT}!`);
    console.log(`> Serving static files from ${publicDir}`);
  });