Registry / web-framework / connect-static-file

connect-static-file

JSON →
library2.0.0jsnpmunverified

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`).

npm install connect-static-file
INSTALL
IMPORT
SIG · CONNECT-STATIC-FIL
C
connect-static-file
web-frameworkjavascriptv2.0.0
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

staticFile
✓ const staticFile = require('connect-static-file');
✗ import staticFile from 'connect-static-file';
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.
staticFile
✓ const staticFile = require('connect-static-file');
✗ import { staticFile } from 'connect-static-file';
The package provides a default (CommonJS) export, not named exports. Attempting to destructure will result in an undefined symbol.
Middleware Integration
✓ app.use('/my-file.txt', staticFile('path/to/actual/file.txt'));
✗ app.get('/my-file.txt', staticFile('path/to/actual/file.txt'));
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.

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.

const express = require('express'); const staticFile = require('connect-static-file'); const path = require('path'); const fs = require('fs'); const app = express(); const port = 3000; // Create a dummy file for the example const dummyFilePath = path.join(__dirname, 'hello.txt'); fs.writeFileSync(dummyFilePath, 'Hello from connect-static-file!'); // Serve the dummy file at /hello.txt app.use('/hello.txt', staticFile(dummyFilePath, { maxAge: '1d', // Cache for 1 day headers: { 'X-Powered-By': 'connect-static-file' } })); // Serve a pre-gzipped version of a bundle if supported, with a fallback const gzippedBundlePath = path.join(__dirname, 'bundle.js.gz'); const unzippedBundlePath = path.join(__dirname, 'bundle.js'); fs.writeFileSync(unzippedBundlePath, 'console.log("This is the uncompressed bundle.");'); // In a real app, you'd generate gzippedBundlePath via a build step fs.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' app.use('/bundle.js', staticFile(gzippedBundlePath, { encoded: 'gzip', maxAge: '7d' })); app.use('/bundle.js', staticFile(unzippedBundlePath, { maxAge: '7d' })); // Fallback app.listen(port, () => { console.log(`Server listening at http://localhost:${port}`); console.log(`Try accessing: http://localhost:${port}/hello.txt`); console.log(`Try accessing: http://localhost:${port}/bundle.js (will serve gzip if supported by browser)`); }); // Cleanup dummy files on process exit process.on('exit', () => { fs.unlinkSync(dummyFilePath); fs.unlinkSync(gzippedBundlePath); fs.unlinkSync(unzippedBundlePath); });
Debug
Known issues
breakingVersion 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`.
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.
affects: >=2.0.0
breakingVersion 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.
fix
Remove the `acceptRanges` option from your configuration if present, as it is no longer supported.
affects: >=2.0.0
gotchaWhen 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.
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'));`.
affects: >=1.0.0
gotchaThis 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.
fix
For serving entire directories of static assets, consider using `express.static`, `connect-gzip-static`, or `ecstatic`.
affects: >=1.0.0
gotchaThe `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`).
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.
affects: >=1.0.0
Errors
Common errors & fixes
Error: ENOENT: no such file or directory, stat '/path/to/non-existent-file.txt'
The `path` argument provided to `staticFile()` does not point to an actual file that exists on the filesystem.
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.
Cannot GET /my-asset (HTTP 404 response)
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.
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.
Client receives uncompressed file despite `encoded: 'gzip'` in configuration, or `Content-Encoding` header is missing/incorrect.
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.
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.
Upgrade
Version history
2.0.0latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
20 hits · last 30 days
node
18
OpenAI (training)
1
Resources