Static Serve

The @gaman/static package allows you to serve static files (images, CSS, JS, etc.) from a directory. It includes automatic MIME type detection, ETag generation, and support for Brotli/Gzip compression.

Installation

npm

npm install @gaman/static

pnpm

pnpm install @gaman/static

yarn

yarn install @gaman/static

bun

bun install @gaman/static

Usage

Register the static file middleware in your bootstrap file using app.mount():

import { defineBootstrap } from 'gaman';
import { StaticServe } from '@gaman/static';

defineBootstrap(async (app) => {
  // Serve files from the 'public' folder (default)
  app.mount(StaticServe());

  // Or with custom configuration
  app.mount(StaticServe({
    publicPath: './assets',
    rewriteRequestPath: (p) => p.replace(/^\/static/, ''),
    fallbackToIndexHTML: true, // SPA fallback
  }));

  app.mountServer({ http: 3431 });
});

Configuration Options

Option	Type	Default	Description
publicPath	string	"public"	Path to the directory to serve
defaultDocument	string	"index.html"	File to serve when a directory is requested
rewriteRequestPath	(path: string) => string	—	Rewrite request paths (e.g., strip prefix)
fallbackToIndexHTML	boolean	false	Fallback to index.html on 404 (SPA support)
cacheControl	string	—	Customize Cache-Control header
mimes	Record<string, string>	—	Custom MIME type mappings
onFound	(path, ctx) => void	—	Callback when a file is found
onNotFound	(path, ctx) => void	—	Callback when a file is not found

Features

• Automatic Compression: Serves .br or .gz files if they exist and the browser supports it.
• ETag & 304: Automatic ETag generation for efficient browser caching.
• Performance: Built on top of Bun.file() for maximum speed.