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
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Lws
✓ import Lws from 'lws';
✗ const Lws = require('lws')
lws supports both ESM and CJS; programmatic use often starts with importing the Lws class.
blacklistMiddleware
✓ import blacklistMiddleware from 'lws-blacklist';
✗ import { blacklistMiddleware } from 'lws-blacklist';
Assuming lws-blacklist exports a default function that returns the middleware; direct symbol names might vary if it's a class or named export.
Demonstrates programmatic setup of an lws server with lws-blacklist, blocking specific URL patterns like '/admin/(.*)' and '/secret-page.html' using the `--blacklist` option equivalent.
import Lws from 'lws';
import blacklistMiddleware from 'lws-blacklist';
const server = new Lws();
async function startServer() {
try {
const options = {
port: 8000,
stack: ['lws-static'], // Ensure static serving is also enabled
directory: './public', // Serve files from a 'public' directory
blacklist: ['/admin/(.*)', '/secret-page.html'], // Routes to forbid
// For programmatic use, the middleware itself is added to the stack
// but the configuration comes via options that lws-blacklist processes.
// If lws-blacklist exported a direct Koa middleware, it would look like:
// middleware: [blacklistMiddleware({ blacklist: ['/admin/(.*)'] })]
};
await server.start(options);
console.log(`lws-blacklist example server running at http://localhost:${options.port}`);
console.log('Try accessing http://localhost:8000/secret-page.html or http://localhost:8000/admin/dashboard.html');
console.log('Serving static files from ./public');
} catch (error) {
console.error('Failed to start lws server:', error);
}
}
// Create a public directory and some test files
import fs from 'fs';
if (!fs.existsSync('./public')) fs.mkdirSync('./public');
fs.writeFileSync('./public/index.html', '<h1>Hello from lws!</h1><p>Public page.</p>');
fs.writeFileSync('./public/secret-page.html', '<h1>ACCESS DENIED</h1><p>This page should be blocked.</p>');
fs.writeFileSync('./public/admin/dashboard.html', '<h1>Admin Dashboard</h1><p>This page should be blocked.</p>');
startServer();
lws --version
Debug
Known issues
gotchaThe `lws-blacklist` package name and its core functionality utilize the term 'blacklist', which is increasingly being deprecated in favor of 'denylist' or 'blocklist' across the tech industry for reasons of inclusivity. While the functionality remains, newer projects might prefer alternative terminology.fixConsider documenting usage with 'denylist' or 'blocklist' in your own project's context, or explore alternative middleware if this terminology is a concern.
affects: >=1.0.0
breakingThe lws ecosystem uses Koa for its middleware. If there were changes in how lws expects middleware to be structured (e.g., from an Express-style to a Koa-style signature, or changes in context object properties), older versions of lws-blacklist might not be compatible with newer lws versions.fixAlways check the lws documentation and lws-blacklist release notes for compatibility when upgrading major versions of either package. Ensure your middleware functions conform to the Koa (ctx, next) => {} signature. affects: <3.0.0 to >=3.0.0 (hypothetical, typical major version bump reason)
gotchaRegular expressions provided to `--blacklist` are matched against the request path. Misconfigured or overly broad regexes can block legitimate routes, while overly specific ones can fail to block intended targets. Ensure correct regex syntax and test thoroughly.fixTest your blacklist patterns thoroughly with expected valid and invalid URLs. Online regex testers can help in validating patterns. Remember that regex special characters (e.g., '.', '*', '?', '+') need to be escaped if you mean them literally.
affects: >=1.0.0
gotchaThe `lws-blacklist` package has an `npm audit` warning due to its transitive dependency on `path-to-regexp` (GHSA-9wv6-86v2-598j). This indicates a potential security vulnerability in a sub-dependency, though its direct impact on lws-blacklist's specific use case might vary.fixRegularly run `npm audit fix` and `npm update` to ensure all dependencies are at their latest, patched versions. If the vulnerability persists, consult the `lws-blacklist` GitHub issues for official patches or recommended workarounds.
affects: >=1.0.0
gotchaThe package `lws-blacklist` version `3.0.0` was last published approximately six years ago, and its core dependency `lws` also has a noted 'not healthy version release cadence'. This implies a potentially slower maintenance cycle and a reduced likelihood of new feature development or rapid vulnerability patches.fixEvaluate the project's long-term maintenance status and community activity if active development or immediate patching of issues is critical for your application. Consider contributing to the project or forking it if specific needs arise.
affects: >=3.0.0
Errors
Common errors & fixes
Error: Middleware 'lws-blacklist' not found or invalid.
The lws server could not locate or correctly load the `lws-blacklist` module, either due to incorrect installation, a typo in the stack name, or an incompatible version.
fixEnsure `lws-blacklist` is installed (`npm install lws-blacklist`). If using the CLI `--stack` option, ensure `lws-blacklist` is spelled correctly. For programmatic use, verify the import path and that the module exports a valid middleware factory function.
Request to '/admin/dashboard' was not blocked as expected.
The regular expression provided for blacklisting did not correctly match the intended route, or the blacklist middleware is not correctly ordered in the `lws` stack.
fixDouble-check your regex patterns for accuracy. Use a regex testing tool to confirm they match your target paths. In `lws`, middleware order matters; ensure `lws-blacklist` is positioned early enough in your middleware stack to intercept requests before other middleware might process or serve them.
TypeError: Cannot read properties of undefined (reading 'blacklist')
This error typically occurs if `lws-blacklist` is being used programmatically but its configuration object is missing or malformed, or if the `lws` instance is not correctly passing options to the middleware.
fixWhen using `lws-blacklist` programmatically, ensure you pass the `blacklist` array of patterns as expected by its API. For CLI usage, verify the `--blacklist` option is correctly formatted with valid path arguments.
Audit
Dependencies
lwsrequiredCore dependency; lws-blacklist is an lws middleware.
path-to-regexprequiredTransitive dependency with known audit warning, used for route matching.