Registry / web-framework / lws
library1.2.8jsnpmunverified

Lws is a lean, modular web server designed for rapid full-stack development, serving as an application core for quickly launching local HTTP, HTTPS, and HTTP2 servers. Its behavior is entirely customizable through a plugin system built on Koa middleware, allowing users to load only the specific functionalities required for their projects. Key differentiators include its small footprint, 100% personalizable nature, support for custom views for activity visualization, and both programmatic and command-line interfaces. The current stable version is 4.2.0. The project maintains an active release cadence, with recent updates focusing on Node.js compatibility and refining its modular plugin architecture.

npm install lws
INSTALL
IMPORT
SIG · LWS
L
lws
web-frameworkjavascriptv1.2.8
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.

Lws
import Lws from 'lws';
const Lws = require('lws');
Since v4.0.0, Lws is an ESM-only package. CommonJS `require()` is not supported.
Lws (Named Import)
import Lws from 'lws';
import { Lws } from 'lws';
The primary Lws class is exported as a default export, not a named one. Using named import will result in a runtime error.
Middleware Plugin Example
import MyPlugin from './my-plugin.js';
const MyPlugin = require('./my-plugin.js');
Custom plugins are typically written as ESM modules to integrate seamlessly with Lws v4+.

This quickstart demonstrates how to programmatically initialize and start an Lws server, including how to define and register simple inline Koa-style middleware to handle requests and serve custom responses for specific paths.

import Lws from 'lws'; import { resolve } from 'path'; // Define a simple Koa-style middleware plugin class HelloWorldPlugin { middleware() { return async (ctx, next) => { // Serve a custom response for the root path if (ctx.path === '/') { ctx.body = 'Hello from Lws! This is a programmatic server.'; ctx.type = 'text/plain'; return; // Prevent further middleware from processing this request } // Allow other middleware to handle the request await next(); }; } } // Define another simple middleware to catch unhandled requests class NotFoundPlugin { middleware() { return async (ctx, next) => { await next(); // If the request was not handled by any preceding middleware if (!ctx.body) { ctx.body = '404 Not Found from Lws Custom Stack!'; ctx.status = 404; ctx.type = 'text/plain'; } }; } } async function startLwsServer() { const server = new Lws({ port: 8000, // The `stack` option accepts an array of plugin instances. stack: [ new HelloWorldPlugin(), new NotFoundPlugin() // To use external plugins like lws-static, ensure they are installed: // { module: require('lws-static'), options: { directory: resolve(process.cwd(), 'public') } } ] }); server.start(); console.log(`Lws server listening on http://localhost:${server.port}`); console.log('Test by visiting: http://localhost:8000/'); console.log('Test 404 by visiting: http://localhost:8000/non-existent-path'); } startLwsServer().catch(console.error);
lws --version
Debug
Known issues
breakingLws v4.0.0 dropped support for consuming its API from CommonJS modules. The package is now ESM-only. Attempting to `require('lws')` will result in an `ERR_REQUIRE_ESM` error.
fix
Migrate your project to use ECMAScript Modules (ESM) syntax (`import ... from 'lws';`) or ensure your Node.js environment is configured for ESM.
affects: >=4.0.0
breakingLws v4.0.0 initially raised the minimum required Node.js version to v14. Users running older Node.js versions (e.g., v12) would encounter compatibility issues.
fix
Upgrade your Node.js environment to v14 or higher if using Lws versions 4.0.0 through 4.0.x. For versions 4.1.0 and above, Node.js v12.20+ is supported.
affects: 4.0.0 - 4.0.x
gotchaFrom v4.1.0 onwards, Lws extended its Node.js compatibility back to v12.20. While v4.0.x required Node.js v14+, the current stable versions support v12.20+ due to retrofitted 'exports' support in Node.js.
fix
Ensure your Node.js version is at least v12.20. If you are specifically targeting the 4.0.x branch, you will still need Node.js v14+.
affects: >=4.1.0
breakingLws v4.0.0 removed the implicit `lws-` prefix for plugin names when specified via the `--stack` CLI option. Previously, `--stack static` would correctly load `lws-static`, but this behavior is now deprecated to avoid ambiguity.
fix
Always use the full plugin name including the `lws-` prefix when specifying plugins via the `--stack` option (e.g., `--stack lws-static lws-index`).
affects: >=4.0.0
gotchaLws is an application core; its core functionality is minimal. Most useful web server features (like static file serving, proxying, logging) are provided by separate `lws-*` middleware plugins. These plugins must be installed separately.
fix
Install necessary `lws-*` plugins (e.g., `npm install lws-static lws-log`) and include them in your server's stack, either via CLI (`lws --stack lws-static`) or programmatically.
affects: >=3.0.0
Errors
Common errors & fixes
Error [ERR_REQUIRE_ESM]: require() of ES module /path/to/node_modules/lws/index.js from /your/app.js not supported. Instead change the require of index.js in /your/app.js to a dynamic import() which is also supported. Or change the all of the js files to .mjs extension or type: module in package.json.
Attempting to import Lws using CommonJS `require()` syntax in an environment that expects ESM.
fix
Change your import statement from `const Lws = require('lws');` to `import Lws from 'lws';`. Ensure your project's `package.json` has `"type": "module"` or your file uses the `.mjs` extension.
Error: Cannot find module 'lws-static' (or similar 'lws-*' plugin name)
An `lws-*` plugin was specified in the stack (either via CLI or programmatically) but has not been installed as a project dependency.
fix
Install the missing plugin using npm (e.g., `npm install --save-dev lws-static`) or yarn (`yarn add --dev lws-static`).
The Lws server requires Node.js v12.20 or greater. You are using Node.js v10.x.x.
The installed Node.js version does not meet the minimum requirement for Lws (currently v12.20+).
fix
Upgrade your Node.js environment to version 12.20 or newer. Consider using a Node.js version manager like `nvm` to easily switch between versions.
TypeError: (0 , lws__WEBPACK_IMPORTED_MODULE_0__.default) is not a constructor
You are attempting to use `import { Lws } from 'lws';` when `Lws` is a default export, not a named export. This often happens with bundlers like Webpack or Babel.
fix
Correct the import statement to `import Lws from 'lws';` to correctly access the default exported class.
Upgrade
Version history
1.2.8latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
2 hits · last 30 days
node
2
Resources
lws — npm install lws · libregistry