{"id":17554,"library":"connect-static-file","title":"connect-static-file","description":"connect-static-file is a lightweight middleware for Connect and Express applications designed to serve a single static file. Unlike `express.static` which serves entire directories, this module focuses on efficiently delivering a specified file, making it ideal for specific assets like `index.html` or a `robots.txt`. The current stable version is 2.0.0, with its last major update occurring in 2017, suggesting a low-cadence, maintenance-focused project. A key differentiator is its `encoded` option, allowing developers to serve pre-compressed files (e.g., gzip) directly, optimizing client delivery by avoiding on-the-fly compression. It also provides fine-grained control over HTTP caching headers like `ETag`, `Last-Modified`, and `Cache-Control` (`maxAge`).","status":"maintenance","version":"2.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/Joris-van-der-Wel/connect-static-file","tags":["javascript","static","gzip","gz","express","connect","file","compress","middleware"],"install":[{"cmd":"npm install connect-static-file","lang":"bash","label":"npm"},{"cmd":"yarn add connect-static-file","lang":"bash","label":"yarn"},{"cmd":"pnpm add connect-static-file","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"This package is a CommonJS module. Native ESM import syntax will not work without a bundler or specific Node.js loader configurations. Use `require()` for direct consumption.","wrong":"import staticFile from 'connect-static-file';","symbol":"staticFile","correct":"const staticFile = require('connect-static-file');"},{"note":"The package provides a default (CommonJS) export, not named exports. Attempting to destructure will result in an undefined symbol.","wrong":"import { staticFile } from 'connect-static-file';","symbol":"staticFile","correct":"const staticFile = require('connect-static-file');"},{"note":"While `app.get` might technically work, `app.use` is the idiomatic way to mount middleware that processes all HTTP methods for a given path prefix, as `connect-static-file` is designed to be a general-purpose serving middleware.","wrong":"app.get('/my-file.txt', staticFile('path/to/actual/file.txt'));","symbol":"Middleware Integration","correct":"app.use('/my-file.txt', staticFile('path/to/actual/file.txt'));"}],"quickstart":{"code":"const express = require('express');\nconst staticFile = require('connect-static-file');\nconst path = require('path');\nconst fs = require('fs');\n\nconst app = express();\nconst port = 3000;\n\n// Create a dummy file for the example\nconst dummyFilePath = path.join(__dirname, 'hello.txt');\nfs.writeFileSync(dummyFilePath, 'Hello from connect-static-file!');\n\n// Serve the dummy file at /hello.txt\napp.use('/hello.txt', staticFile(dummyFilePath, {\n  maxAge: '1d', // Cache for 1 day\n  headers: { 'X-Powered-By': 'connect-static-file' }\n}));\n\n// Serve a pre-gzipped version of a bundle if supported, with a fallback\nconst gzippedBundlePath = path.join(__dirname, 'bundle.js.gz');\nconst unzippedBundlePath = path.join(__dirname, 'bundle.js');\nfs.writeFileSync(unzippedBundlePath, 'console.log(\"This is the uncompressed bundle.\");');\n// In a real app, you'd generate gzippedBundlePath via a build step\nfs.writeFileSync(gzippedBundlePath, Buffer.from('\\x1f\\x8b\\x08\\x00\\x00\\x00\\x00\\x00\\x00\\x03\\xcbH\\xcd\\xc9\\xc9W(\\xcf/\\xcaIQ\\x04\\x00\\x9d\\x1a\\xa0*\\x1e\\x00\\x00\\x00', 'binary')); // Minimal gzip for 'Hello'\n\napp.use('/bundle.js', staticFile(gzippedBundlePath, { encoded: 'gzip', maxAge: '7d' }));\napp.use('/bundle.js', staticFile(unzippedBundlePath, { maxAge: '7d' })); // Fallback\n\n\napp.listen(port, () => {\n  console.log(`Server listening at http://localhost:${port}`);\n  console.log(`Try accessing: http://localhost:${port}/hello.txt`);\n  console.log(`Try accessing: http://localhost:${port}/bundle.js (will serve gzip if supported by browser)`);\n});\n\n// Cleanup dummy files on process exit\nprocess.on('exit', () => {\n  fs.unlinkSync(dummyFilePath);\n  fs.unlinkSync(gzippedBundlePath);\n  fs.unlinkSync(unzippedBundlePath);\n});","lang":"javascript","description":"This quickstart demonstrates how to set up an Express server to serve a single text file and a pre-gzipped JavaScript bundle using `connect-static-file`, including a fallback for browsers that don't support gzip. It shows basic caching and custom header options."},"warnings":[{"fix":"Upgrade Node.js to a supported version (>=0.12) or downgrade to `connect-static-file@1.x` if you must use Node.js v0.10.","message":"Version 2.0.0 removed support for Node.js v0.10. If you are on an older Node.js runtime, you must use `connect-static-file@1.x`.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Remove the `acceptRanges` option from your configuration if present, as it is no longer supported.","message":"Version 2.0.0 removed the `acceptRanges` option, which was previously enabled by default. This change should have minimal impact as the option offered little value.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Always include a fallback middleware for the unencoded file immediately after the `encoded` version for the same route, e.g., `app.use('/bundle.js', staticFile('bundle.js.gz', {encoded: 'gzip'})); app.use('/bundle.js', staticFile('bundle.js'));`.","message":"When using the `encoded` option (e.g., `encoded: 'gzip'`), `connect-static-file` will only serve the pre-encoded file if the client's `Accept-Encoding` header supports it. If not, the request is passed to the next middleware. You MUST implement a fallback middleware to serve an unencoded version or an alternative encoding if the client doesn't support the specified `encoded` type.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"For serving entire directories of static assets, consider using `express.static`, `connect-gzip-static`, or `ecstatic`.","message":"This middleware is designed to serve a *single* specific file per instance. It does not perform directory lookups or serve multiple files based on a path segment. Attempts to use it like `express.static` for entire directories will fail.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure `extensions` is explicitly set to an array (e.g., `['html', 'htm']`) if you want to use it for extension-less URLs. Remember it won't affect requests for URLs that already specify an extension.","message":"The `extensions` option is disabled by default (`false`) and is ignored if the requested URL already includes a file extension. It only applies if the initial file `path` cannot be found and the URL has no explicit extension (e.g., `/my-page` rather than `/my-page.html`).","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-23T00:00:00.000Z","next_check":"2026-07-22T00:00:00.000Z","problems":[{"fix":"Verify that the file path argument in `staticFile('/your/path', ...)` is correct and the file exists at that location with proper read permissions for the Node.js process.","cause":"The `path` argument provided to `staticFile()` does not point to an actual file that exists on the filesystem.","error":"Error: ENOENT: no such file or directory, stat '/path/to/non-existent-file.txt'"},{"fix":"Ensure the URL path provided to `app.use('/your-url', staticFile(...))` exactly matches the path clients are requesting. If using the `encoded` option, verify a non-encoded fallback middleware is provided immediately after the encoded version for browsers that don't support the encoding.","cause":"The route path (e.g., `/my-asset`) used with `app.use()` does not match the incoming request URL, or no fallback is provided for `encoded` files when the client doesn't support the encoding.","error":"Cannot GET /my-asset (HTTP 404 response)"},{"fix":"Confirm the client's `Accept-Encoding` header. If it includes 'gzip', ensure your middleware order is correct with the `encoded` version preceding any unencoded fallback for the same route. Double-check the spelling and value of the `encoded` option.","cause":"The client's `Accept-Encoding` header does not include 'gzip', or the middleware order is incorrect, causing a fallback to be hit prematurely, or the `encoded` option is misspelled.","error":"Client receives uncompressed file despite `encoded: 'gzip'` in configuration, or `Content-Encoding` header is missing/incorrect."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}