@prexjs/send

Streaming static file server for Node.js HTTP servers with range requests, conditional GET, and cache-control.

@prexjs/send streams static files directly to HTTP response objects. It includes complete support for byte-range requests (RFC 7233), conditional GET verification via ETags and Last-Modified headers (RFC 7232), directory indexing, dotfile security policies, and Cache-Control headers.

Features

• Byte Range Serving: Supports full, multi-part, and partial content requests (206 Partial Content) for videos and media streaming.
• Conditional Caching: Automatically handles If-None-Match, If-Modified-Since, and 304 Not Modified status codes.
• Security & Path Traversal Prevention: Safely roots file requests and blocks path escapes or malicious dotfiles.
• Granular Options: Configurable etag, lastModified, maxAge, immutable, index, and extension fallback.
• Stream Lifecycle Management: Cleanly tears down file descriptors on connection closures using @prexjs/finished.

Installation

Install using your preferred package manager:

# npm
npm install @prexjs/send

# pnpm
pnpm add @prexjs/send

# Yarn
yarn add @prexjs/send

# Bun
bun add @prexjs/send

Quick start

import http from 'node:http';
import send from '@prexjs/send';

const server = http.createServer((req, res) => {
  // Stream files from ./public directory
  send(req, req.url || '/', {
    root: './public',
    index: ['index.html'],
    maxAge: '1d',
  })
    .on('error', (err) => {
      res.statusCode = err.status || 500;
      res.end(err.message);
    })
    .pipe(res);
});

server.listen(3000);

API

send(req, path, [options])

Creates a new SendStream instance.

• req: The incoming http.IncomingMessage request.
• path: Target file path relative to root.
• options:
  • root: Root directory for file serving (required for relative path security).
  • acceptRanges: Enable HTTP Range requests (default: true).
  • cacheControl: Enable Cache-Control header (default: true).
  • dotfiles: How to treat dotfiles: 'allow', 'deny' (403), or 'ignore' (404) (default: 'ignore').
  • etag: Enable ETag generation (default: true).
  • extensions: File extension fallback array (e.g. ['html', 'htm']).
  • immutable: Enable immutable directive in Cache-Control (default: false).
  • index: Default file name when requesting a directory (default: 'index.html').
  • lastModified: Enable Last-Modified header (default: true).
  • maxAge: Cache max age in milliseconds or string like '1d', '2h' (default: 0).

Compatibility

• Node.js >= 18.0.0
• Supports both ESM and CommonJS
• TypeScript 5.0+

Related Packages

• @prexjs/serve-static: Connect/Express static file serving middleware.
• @prexjs/etag: HTTP ETag generator.
• @prexjs/range-parser: Range header parser.

License

MIT