Registry / web-framework / lws-static

lws-static

JSON →
library3.1.1jsnpmunverified

lws-static is a dedicated middleware plugin for the lws (local-web-server) ecosystem, designed to serve static files efficiently. It internally wraps koa-static, leveraging its robust capabilities for features like caching and directory indexing. The package is currently at version 3.1.1, actively maintained with periodic updates to its underlying dependencies, notably koa-static, and to ensure compatibility with the lws core framework. Its primary differentiator is seamless integration with lws's configuration system, allowing static file serving to be configured via concise CLI arguments or a programmatic lws setup. This approach simplifies the creation of development servers by offering a unified interface for defining the static root directory, cache control (max-age), request deferral, custom index files, and additional filename extensions, abstracting away direct koa-static configuration for lws users.

npm install lws-static
INSTALL
IMPORT
SIG · LWS-STATIC
L
lws-static
web-frameworkjavascriptv3.1.1
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
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 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

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

createStaticMiddleware
import createStaticMiddleware from 'lws-static';
const createStaticMiddleware = require('lws-static');
Since v3.0.0, lws-static is an ESM-only package. The default export is a function that returns the Koa middleware creator.
Lws
import Lws from 'local-web-server';
The lws-static middleware is designed to be used with the local-web-server (lws) framework, which is imported separately.
StaticMiddlewareOptions
import type { Options } from 'lws-static';
The `Options` type represents the configuration object passed to the `createStaticMiddleware` function, largely mirroring `koa-static`'s options.

Demonstrates programmatic setup of `lws` with `lws-static` to serve static files from a temporary directory. It configures caching, an index file, and proper cleanup.

import Lws from 'local-web-server'; import createStaticMiddleware from 'lws-static'; import path from 'path'; import fs from 'fs'; // Create a temporary directory and file for demonstration const tempDir = path.join(process.cwd(), 'lws-public-temp'); const tempFile = path.join(tempDir, 'index.html'); // Ensure the directory exists and contains an index file fs.mkdirSync(tempDir, { recursive: true }); fs.writeFileSync(tempFile, '<h1>Hello from lws-static!</h1>', 'utf8'); const lws = new Lws({ port: 8080, stack: [ createStaticMiddleware({ directory: tempDir, // Serve from the temporary 'lws-public-temp' directory maxAge: 3600, // Cache for 1 hour (in seconds) index: 'index.html', // Default file if a directory is requested defer: true // Allow other downstream middleware to respond first }) ] }); lws.start(); console.log(`lws-static server running on http://localhost:8080`); console.log(`Serving files from: ${tempDir}`); console.log('Access http://localhost:8080 to see the static content.'); console.log('Press Ctrl+C to stop the server and clean up.'); // Clean up on exit process.on('SIGINT', () => { console.log('\nStopping server and cleaning up...'); lws.server.close(() => { if (fs.existsSync(tempDir)) { fs.rmSync(tempDir, { recursive: true, force: true }); console.log('Temporary directory cleaned up.'); } process.exit(0); }); });
lws --version
Debug
Known issues
breaking`lws-static` versions 3.0.0 and above are ESM-only modules. Attempting to use `require()` will result in a runtime `ERR_REQUIRE_ESM` error.
fix
Migrate your project to use ES modules (`import` statements) or pin `lws-static` to a version prior to 3.0.0 if CommonJS is strictly required for your project.
affects: >=3.0.0
breakingThe v3.0.0 release of `lws-static` raised its minimum requirements to Node.js v14 or higher and `local-web-server` (lws) v6 or higher, primarily due to the transition to ESM and updated internal dependencies.
fix
Ensure your Node.js environment is updated to at least v14 and upgrade your `local-web-server` package to version 6.x or newer to ensure compatibility.
affects: >=3.0.0
gotchaWhen configuring `lws-static` via the `lws` command-line interface, all options must be prefixed with `--static.`, e.g., `--static.maxage 3600`. Programmatic usage passes options directly to the middleware factory.
fix
Consult the `lws-static` README or `lws --help` for the correct option syntax when using the CLI, and ensure programmatic options are passed as an object to the `createStaticMiddleware()` function.
affects: >=1.0.0
gotcha`lws-static` relies on `koa-static` for its core functionality. While most options are passed through directly, in-depth understanding of `koa-static`'s behavior (e.g., how it handles URL rewriting or directory listings) can be crucial for complex configurations or debugging unexpected behavior.
fix
Refer to the official `koa-static` documentation for detailed information on static file serving mechanisms and advanced configuration options.
affects: >=1.0.0
Errors
Common errors & fixes
Error [ERR_REQUIRE_ESM]: require() of ES Module /path/to/node_modules/lws-static/index.js from /path/to/your/app.js not supported.
`lws-static` v3.0.0 and later are ESM-only modules, and you are attempting to import it using CommonJS `require()` syntax.
fix
Update your import statement from `const middleware = require('lws-static');` to `import middleware from 'lws-static';` and ensure your project is configured for ES modules (e.g., using `"type": "module"` in `package.json` or `.mjs` file extensions).
TypeError: createStaticMiddleware is not a function
This typically occurs if the import path is incorrect, or if the imported symbol is not the default function that creates the middleware (e.g., a named import was used instead of the default export).
fix
Ensure you are using `import createStaticMiddleware from 'lws-static';` and that you are calling `createStaticMiddleware()` as a function when adding it to your `lws` stack, e.g., `stack: [createStaticMiddleware({ directory: './public' })]`.
Error: ENOENT: no such file or directory, stat '/path/to/your/specified-directory'
The `directory` option provided to `lws-static` (either via CLI `--directory` or programmatically) points to a path that does not exist on the filesystem.
fix
Double-check the `directory` path for typos or incorrect relative paths. Ensure the directory exists and that your application has the necessary read permissions. Consider using absolute paths with `path.join(__dirname, 'your-static-folder')` for robustness.
Upgrade
Version history
3.1.1latest on npm
Audit
Dependencies
koa-staticrequiredProvides the core static file serving logic and options.
Agent activity
4 hits · last 30 days
node
4
Resources