or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

cli.mdconfiguration.mdcore-server.mdindex.md
tile.json

tessl/npm-st

A module for serving static files with etags, caching, gzip compression, CORS support, and directory indexing.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/st@3.0.x

To install, run

npx @tessl/cli install tessl/npm-st@3.0.0

index.mddocs/

st (Static File Server)

st is a comprehensive static file server module for Node.js applications that enables efficient serving of static files with advanced features including etags, intelligent caching, CORS support, and gzip compression. It offers both programmatic API for integration into existing HTTP servers and Express applications, as well as a command-line interface for standalone static file serving.

Package Information

  • Package Name: st
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install st

Core Imports

const st = require('st');

For ES modules:

import st from 'st';

Access to Mount class:

const { Mount } = require('st');
// or
const st = require('st');
const Mount = st.Mount;

Basic Usage

const st = require('st');
const http = require('http');

// Simple static file serving
http.createServer(
  st(process.cwd())
).listen(1337);

// With configuration options
const mount = st({
  path: './static',
  url: '/static',
  cache: true,
  gzip: true,
  cors: true
});

http.createServer((req, res) => {
  if (mount(req, res)) {
    return; // Request handled by st
  }
  res.end('Not a static file');
}).listen(1338);

Architecture

st is built around several key components:

  • Factory Function: st() creates configured request handler functions
  • Mount Class: Internal class managing file serving, caching, and request processing
  • Multi-level Caching: LRU caches for file descriptors, stats, content, indexes, and directory listings
  • Security Layer: Path traversal prevention and dot-file access controls
  • Compression Engine: Automatic gzip compression with content negotiation
  • CLI Server: Standalone HTTP server with extensive configuration options

Capabilities

Core Server Function

The main st() factory function and Mount class provide the core static file serving functionality with multiple configuration options.

function st(path: string): RequestHandler;
function st(path: string, url: string): RequestHandler;
function st(path: string, url: string, options: StOptions): RequestHandler;
function st(options: StOptions): RequestHandler;

interface RequestHandler {
  (req: http.IncomingMessage, res: http.ServerResponse, next?: Function): boolean;
  _this: Mount;
}

Core Server Function

Configuration Options

Comprehensive configuration system supporting caching, security, performance, and behavior customization.

interface StOptions {
  path: string;
  url?: string;
  index?: boolean | string;
  dot?: boolean;
  passthrough?: boolean;
  gzip?: boolean;
  cors?: boolean;
  cachedHeader?: boolean;
  cache?: CacheOptions | false;
}

interface CacheOptions {
  fd?: CacheConfig;
  stat?: CacheConfig;
  content?: ContentCacheConfig;
  index?: CacheConfig;
  readdir?: CacheConfig;
}

Configuration Options

CLI Interface

Command-line interface for running st as a standalone HTTP server with extensive configuration options.

st [options]

# Common options:
# -p, --port PORT        Listen on PORT (default=1337)
# -d, --dir DIRECTORY    Serve the contents of DIRECTORY
# -u, --url /url         Serve at this mount url (default=/)
# --cors                 Enable CORS headers
# --no-cache             Disable all caching

CLI Interface

Dependencies

st requires the following npm packages:

  • lru-cache (^11.1.0) - LRU cache implementation for file descriptors, stats, and content
  • bl (^6.1.0) - Buffer list for collecting streamed data
  • fd (^0.0.3) - File descriptor management
  • mime (^3.0.0) - MIME type detection based on file extensions
  • negotiator (^1.0.0) - HTTP content negotiation utilities
  • graceful-fs (^4.2.3) - Optional drop-in replacement for fs module with better error handling

Types

// Module exports
module.exports = st;
module.exports.Mount = Mount;

class Mount {
  constructor(options: StOptions);
  serve(req: http.IncomingMessage, res: http.ServerResponse, next?: Function): boolean;
  getCacheOptions(options: StOptions): ProcessedCacheOptions;
  getUriPath(url: string): string | number | false;
  getPath(uriPath: string): string;
  getUrl(filePath: string): string | false;
  error(error: Error | number, res: http.ServerResponse): void;
  index(path: string, req: http.IncomingMessage, res: http.ServerResponse): void;
  autoindex(path: string, req: http.IncomingMessage, res: http.ServerResponse): void;
  file(path: string, fd: number, stat: fs.Stats, etag: string, req: http.IncomingMessage, res: http.ServerResponse, end: Function): void;
  cachedFile(path: string, stat: fs.Stats, etag: string, req: http.IncomingMessage, res: http.ServerResponse): void;
  streamFile(path: string, fd: number, stat: fs.Stats, etag: string, req: http.IncomingMessage, res: http.ServerResponse, end: Function): void;
}

interface CacheConfig {
  max?: number;
  maxAge?: number;
  ignoreFetchAbort?: boolean;
}

interface ContentCacheConfig extends CacheConfig {
  maxSize?: number;
  sizeCalculation?: (item: any) => number;
  cacheControl?: string;
}