Node.js HTTP Static File Streaming

Common errors

• TypeError: send is not a function

  cause Attempting to destructure `send` from a `require` or `import` statement, or using `require('send')` in an ESM context where only default imports are allowed implicitly.
  fix Use `const send = require('send')` for CommonJS or `import send from 'send'` for ESM. The `send` package provides a default export, not named exports.

• Error: ENOENT: no such file or directory, stat '/path/to/my/app/myFile.txt'

  cause The file specified by the `path` argument combined with the `root` option does not exist, or the `root` option is misconfigured, or the `path` argument is not URL-encoded.
  fix Double-check the `root` option to ensure it points to the correct base directory. Verify that the `path` argument accurately reflects the URL path (which `send` resolves relative to `root`). Ensure the file actually exists on the filesystem and has correct permissions. Remember `path` is URL-encoded, not a raw filesystem path.

• Node.js: `require()` of ES Module ... not supported. Instead change the require to a dynamic import()

  cause Trying to `require()` the `send` package in a CommonJS module when `send` itself might be compiled as an ES Module in newer versions, or vice versa, `import`ing a CJS module in an ESM context without proper handling.
  fix If your project is CommonJS, ensure `send` is installed as a CJS-compatible version or configure your build system to handle ESM. If your project is ESM (e.g., `"type": "module"` in `package.json`), use `import send from 'send'`. Node.js 18+ generally handles interoperability well, but conflicts can arise if `send` is configured as ESM-only without CJS fallback.

Warnings

• breaking Node.js 18 or newer is now required. Older Node.js versions (below 18) are no longer supported by `send@1.1.0` and above. Users on older Node versions must upgrade their environment or stick to `send@0.x.x` versions.
  Fix: Upgrade your Node.js environment to version 18 or higher. Alternatively, pin `send` to a `0.x.x` version.
• breaking Security hardening in `send@1.1.0` explicitly prevents serving files when a requested path ends with a `/`. This changes previous behavior where such paths might have implicitly served an `index.html` or similar. This is a deliberate change to prevent potential path traversal or directory listing issues.
  Fix: Ensure that your application explicitly handles requests for directory paths (e.g., `/images/`) and redirects them to an appropriate resource (e.g., `/images/index.html`) or configures `index` option if `send` is meant to resolve them.
• gotcha The `dotfiles` option's default behavior ('ignore') is subtly different from explicitly setting `'deny'`. The default will ignore dotfiles (e.g., `.env`), but *not* ignore files within directories that begin with a dot (e.g., `/.git/HEAD`). For strict security, explicitly set `dotfiles: 'deny'` to prevent serving any dotfiles or files within dot directories.
  Fix: For explicit control over dotfile handling, set the `dotfiles` option to `'deny'`, `'allow'`, or `'ignore'` as appropriate for your application's security requirements. For example: `send(req, path, { dotfiles: 'deny' })`.
• gotcha The `path` argument passed to `send(req, path, options)` must be a URL-encoded path, not a direct file-system path. Incorrectly providing a raw file-system path will likely result in 'File not found' errors or unexpected routing.
  Fix: Ensure the `path` argument is a URL-encoded string derived from `req.url` or a similar source. If constructing the path manually, use `encodeURIComponent()` if necessary, but generally `req.url` is already suitable.
• gotcha The `send` package has shown an unusual release pattern, with version `0.19.2` being released *after* `1.2.1`. This can lead to confusion about the current stable or recommended version. Always verify the `npm` registry's `latest` tag and release dates.
  Fix: When installing, consider `npm install send@latest` to get the version tagged as `latest` by the maintainers. Refer to the official GitHub repository or npm page for the intended release line and support status.

Install

• npm install send npm
• yarn add send yarn
• pnpm add send pnpm

Imports

• send
  wrong:

  import { send } from 'send'

  correct:

  import send from 'send'

  The primary export is a default function. Named imports are not supported. Works in Node.js environments with 'type: module' in package.json or '.mjs' files.
• send
  wrong:

  const { send } = require('send')

  correct:

  const send = require('send')

  CommonJS `require` is the traditional way to import. The package exports a default function, so destructuring won't work.
• SendStream (type)

  import type { SendStream } from 'send'

  Import the `SendStream` type for use with TypeScript when interacting with the event emitter returned by `send()`.

Quickstart

Demonstrates how to set up a basic Node.js HTTP server using `send` to serve static files from a 'public' directory, handling errors and directory requests.

import http from 'http';
import path from 'path';
import send from 'send';
import { fileURLToPath } from 'url';

// In an ESM module, __dirname is not directly available. Recreate it.
const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);

// Create a simple HTTP server
const server = http.createServer((req, res) => {
  const filePath = path.join(__dirname, 'public', req.url || 'index.html');
  
  // Basic example of creating a public directory and a file
  // For a real application, ensure 'public' directory exists with files
  // or adjust `root` option accordingly.
  // Example: echo '<h1>Hello from send!</h1>' > public/index.html

  send(req, req.url || '/', { root: path.join(__dirname, 'public') })
    .on('error', (err) => {
      if (err.statusCode === 404) {
        res.statusCode = 404;
        res.end('File not found');
      } else {
        res.statusCode = 500;
        res.end('Internal Server Error: ' + err.message);
      }
    })
    .on('directory', () => {
      // Redirect or serve index.html for directory requests if desired
      res.statusCode = 301;
      res.setHeader('Location', req.url + '/index.html');
      res.end('Redirecting to index.html');
    })
    .on('end', () => {
      console.log(`Served: ${req.url}`);
    })
    .pipe(res);
});

const PORT = 3000;
server.listen(PORT, () => {
  console.log(`Server listening on http://localhost:${PORT}`);
  console.log(`Try http://localhost:${PORT}/index.html (create 'public/index.html' first)`);
});