HTTP Static Content Middleware for Node.js

Common errors

• TypeError: require is not a function

  cause Attempting to use `require()` in an ES Module context where it is not defined.
  fix If your project is ESM, ensure your import statements are correctly configured for CommonJS modules, or use a tool like Rollup/Webpack to bundle. Consider using `createRequire` from the `module` built-in module for specific CJS imports in ESM.

• Error: ENOENT: no such file or directory, stat './public/index.html'

  cause The `base` directory configured for static content does not exist or the requested file is not found within it.
  fix Verify that the `base` path provided in `staticContent.create({ base: '...' })` is correct and relative to your application's execution directory, or an absolute path. Ensure the static files you are trying to serve actually exist in that location.

Warnings

• gotcha This package is primarily designed for CommonJS (CJS) environments, using `require()`. Direct ES Module (ESM) imports may not work out of the box and might require a bundler or a CJS wrapper.
  Fix: For ESM projects, consider using a CommonJS compatibility layer or transpiling your code. If possible, stick to `require()` or use a different static serving middleware if ESM is a strict requirement.
• gotcha The `base` static root folder can be resolved from `AppConfig.static` or `AppConfig.base` if available from the `atma-server` context, otherwise it defaults to the Current Working Directory (CWD). This implicit behavior can lead to unexpected file resolution if not explicitly set in `create()` settings.
  Fix: Always explicitly define the `base` option in the `staticContent.create({ base: './your-static-folder' })` settings to ensure predictable file serving paths.
• gotcha Advanced file reading features, such as custom file `read` middlewares, are powered by `atma-io`. While `static-content` can operate independently, leveraging these features requires understanding and potentially installing `atma-io`.
  Fix: Refer to the `atma-io` documentation for details on extending file reading capabilities. Install `atma-io` if you plan to implement custom file processing pipelines.

Install

• npm install static-content npm
• yarn add static-content yarn
• pnpm add static-content pnpm

Imports

• StaticContentMiddleware
  wrong:

  import StaticContentMiddleware from 'static-content';

  correct:

  const StaticContentMiddleware = require('static-content');

  The package is primarily designed for CommonJS. Direct ESM import might require bundler configuration or a CJS wrapper.
• create
  wrong:

  import { create } from 'static-content';

  correct:

  const createStaticMiddleware = require('static-content').create;

  The `create` function is the primary API for initializing the middleware. It's accessed as a property of the main export.
• Cache
  wrong:

  import { Cache } from 'static-content';

  correct:

  const StaticCache = require('static-content').Cache;

  The `Cache` object provides utilities for managing the static content cache, such as checking status and removing specific entries. Accessed as a property of the main CommonJS export.

Quickstart

Demonstrates setting up a basic Node.js HTTP server to serve static files from a 'public' directory, including custom MIME types and caching.

const http = require('http');
const staticContent = require('static-content');

// Create a static content middleware instance
const staticMiddleware = staticContent.create({
    base: './public',
    mimeTypes: {
        'application/javascript': ['mjs']
    },
    extensions: {
        'text/html': {
            encoding: 'UTF-8',
            maxAge: 3600 // Cache for 1 hour
        }
    }
});

// Create a simple HTTP server using the middleware
http.createServer((req, res) => {
    // The middleware handles static content requests
    staticMiddleware(req, res, () => {
        // If static content is not found, handle dynamic content or return 404
        res.writeHead(404, { 'Content-Type': 'text/plain' });
        res.end('404 Not Found');
    });
}).listen(5777, () => {
    console.log('Static server running on http://localhost:5777');
    console.log('Serving files from ./public');
});