{"id":17371,"library":"static-content","title":"HTTP Static Content Middleware for Node.js","description":"This middleware is part of the `atmajs` ecosystem, designed for handling static file serving in Node.js HTTP servers. It provides features like caching, gzipping, and range requests for optimized delivery of various content types including HTML, scripts, images, and videos. It supports custom MIME types, encoding configurations, and integrates seamlessly with `atma-server` and Connect-style middleware stacks. Currently at version 1.2.2, its release cadence is not explicitly defined, but it appears to be a stable, mature component within its specific framework, primarily targeting CommonJS environments. Key differentiators include its tight integration with `atma-io` for advanced file reading and its support for virtual files and custom file `read` middlewares, offering more flexibility than generic static servers.","status":"maintenance","version":"1.2.2","language":"javascript","source_language":"en","source_url":"https://github.com/atmajs/atma-server-static","tags":["javascript"],"install":[{"cmd":"npm install static-content","lang":"bash","label":"npm"},{"cmd":"yarn add static-content","lang":"bash","label":"yarn"},{"cmd":"pnpm add static-content","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Used for advanced file reading middlewares and virtual files.","package":"atma-io","optional":true},{"reason":"Best works with and provides configuration context for the middleware.","package":"atma-server","optional":true},{"reason":"Used in example configurations, indicating compatibility with Connect/Express-like middleware pipelines.","package":"connect","optional":true}],"imports":[{"note":"The package is primarily designed for CommonJS. Direct ESM import might require bundler configuration or a CJS wrapper.","wrong":"import StaticContentMiddleware from 'static-content';","symbol":"StaticContentMiddleware","correct":"const StaticContentMiddleware = require('static-content');"},{"note":"The `create` function is the primary API for initializing the middleware. It's accessed as a property of the main export.","wrong":"import { create } from 'static-content';","symbol":"create","correct":"const createStaticMiddleware = require('static-content').create;"},{"note":"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.","wrong":"import { Cache } from 'static-content';","symbol":"Cache","correct":"const StaticCache = require('static-content').Cache;"}],"quickstart":{"code":"const http = require('http');\nconst staticContent = require('static-content');\n\n// Create a static content middleware instance\nconst staticMiddleware = staticContent.create({\n    base: './public',\n    mimeTypes: {\n        'application/javascript': ['mjs']\n    },\n    extensions: {\n        'text/html': {\n            encoding: 'UTF-8',\n            maxAge: 3600 // Cache for 1 hour\n        }\n    }\n});\n\n// Create a simple HTTP server using the middleware\nhttp.createServer((req, res) => {\n    // The middleware handles static content requests\n    staticMiddleware(req, res, () => {\n        // If static content is not found, handle dynamic content or return 404\n        res.writeHead(404, { 'Content-Type': 'text/plain' });\n        res.end('404 Not Found');\n    });\n}).listen(5777, () => {\n    console.log('Static server running on http://localhost:5777');\n    console.log('Serving files from ./public');\n});\n","lang":"javascript","description":"Demonstrates setting up a basic Node.js HTTP server to serve static files from a 'public' directory, including custom MIME types and caching."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always explicitly define the `base` option in the `staticContent.create({ base: './your-static-folder' })` settings to ensure predictable file serving paths.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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`.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"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.","cause":"Attempting to use `require()` in an ES Module context where it is not defined.","error":"TypeError: require is not a function"},{"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.","cause":"The `base` directory configured for static content does not exist or the requested file is not found within it.","error":"Error: ENOENT: no such file or directory, stat './public/index.html'"}],"ecosystem":"npm","meta_description":null}