Registry / web-framework / local-web-server

local-web-server

library5.4.0jsnpmunverified

local-web-server is a lean, modular web server designed for rapid full-stack development. As a distribution of the core `lws` package, it bundles a starter pack of useful middleware, enabling functionalities like serving static files, Single Page Applications (SPAs), URL rewriting, CORS, and mock APIs out-of-the-box. The current stable version is 5.4.0, with regular updates addressing bug fixes and new features. It supports HTTP, HTTPS, and HTTP2, offering both programmatic and command-line interfaces. Key differentiators include its small footprint, modular design allowing users to load only required behaviors, and comprehensive features for prototyping back-end services or front-end applications. It requires Node.js v12.20 or newer.

web-framework http-networking

npm install local-web-server

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · LOCAL-WEB-SERVER

local-web-server

web-frameworkjavascriptv5.4.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.

createServer

✓ import createServer from 'local-web-server'

✗ const createServer = require('local-web-server')

Since v5.0.0, local-web-server is an ES module and primarily used with `import`. The default export is a factory function to create a server instance.

ServerOptions

✓ import type { LwsOptions } from 'lws'

While `local-web-server` is a distribution, its configuration options are defined by the underlying `lws` package. Import `LwsOptions` (or similar, depending on `lws` version) directly from 'lws' for type safety. No direct type export from 'local-web-server' itself for server options.

CLI 'ws' command

✓ npx ws [options]

The primary way to use local-web-server is via its command-line interface, `ws`. `npx` is recommended to run the local package executable.

This quickstart demonstrates programmatically configuring a local web server for SPA routing, API rewriting, CORS, and logging.

import createServer from 'local-web-server'; // Create a server instance with common development features const server = createServer({ port: process.env.PORT ? parseInt(process.env.PORT) : 8000, // Serve static files from the current directory // local-web-server includes static serving by default if 'root' is not specified. // This explicitly sets the root to the 'public' directory if it exists. root: './public', // Enable Single Page Application (SPA) routing, redirecting all non-file requests to index.html spa: 'index.html', // Enable CORS for all origins, useful for local development with separate API servers cors: true, // Rewrite API requests to a remote backend rewrite: { '/api/(.*)': 'https://jsonplaceholder.typicode.com/$1' }, // Display a QR code in the terminal for easy mobile access qr: true, // Log requests in 'dev' format log: 'dev' }); server.start(); console.log(`Local Web Server running at http://localhost:${server.port}`); console.log(`Serving static files from: ${server.options.root || './'}`);

ws --version

Debug

Known issues

breakinglocal-web-server v5.0.0 dropped support for Node.js versions older than v14. Subsequent v5.1.0 extended support back to Node.js v12.20. Users on older Node.js environments must upgrade to at least v12.20.

fix

Upgrade Node.js to v12.20 or newer. Check your `node` version with `node -v`.

affects: >=5.0.0

breakingVersion 5.0.0 removed CommonJS support. The package is now exclusively an ES module, requiring `import` syntax. Direct `require()` calls will no longer work.

fix

Refactor your application to use ES module `import` syntax (e.g., `import createServer from 'local-web-server';`) and ensure your project is configured for ESM (e.g., `"type": "module"` in `package.json`).

affects: >=5.0.0

breakingThe ability to use shortened plugin names (e.g., `--stack static` instead of `--stack lws-static`) was removed in v5.0.0 to prevent ambiguity and potential module loading issues.

fix

Always use the full `lws-` prefixed name for middleware plugins (e.g., `--stack lws-static`).

affects: >=5.0.0

breakingIn v3.0.0, the `--websocket` and `--server` options were removed. WebSocket support now requires implementing it via a middleware plugin.

fix

For WebSockets, implement a custom middleware. Consult the `lws` wiki for examples on creating middleware for specific functionalities.

affects: >=3.0.0 <5.0.0

gotchaWhen rewriting requests, if your local connection is insecure (HTTP) and the remote server sets a `Secure` cookie, local-web-server versions prior to v5.4.0 might struggle with `SameSite=none` alongside `Secure`. v5.4.0 explicitly removes `SameSite=none` and `Secure` attributes from cookies when proxying to insecure connections to ensure browser compatibility.

fix

Upgrade to local-web-server v5.4.0 or newer. If upgrading is not immediately possible, consider configuring the remote server to not set `Secure` or `SameSite=none` cookies for development environments, or use HTTPS locally if possible.

affects: <5.4.0

Errors

Common errors & fixes

SyntaxError: Cannot use import statement outside a module

Attempting to `import` local-web-server in a CommonJS (`.js` without `"type": "module"` or `.cjs`) file after v5.0.0 removed CommonJS support.

fix

Ensure your file is treated as an ES module by using a `.mjs` extension or by adding `"type": "module"` to your `package.json`. If using an older Node.js version, upgrade to v12.20+.

Error: listen EADDRINUSE: address already in use :::8000

Another process is already using the specified port (default is 8000), or a previous instance of the server was not properly shut down.

fix

Specify a different port using the `--port` CLI option or `port` configuration property (e.g., `ws --port 3000`). Alternatively, identify and terminate the process currently using the port.

404 Not Found (for client-side routes in a Single Page Application)

The server is not configured to handle client-side routing, so requests for paths that don't correspond to physical files result in a 404.

fix

Use the `--spa index.html` CLI option or `spa: 'index.html'` configuration property to tell local-web-server to serve `index.html` for non-existent file paths, allowing client-side routers to take over.

ERR_MODULE_NOT_FOUND: Cannot find module 'lws-static' from '...' when using a custom stack.

A custom middleware plugin was specified without being installed as a dependency in the project.

fix

Install the required `lws-*` middleware packages (e.g., `npm install lws-static`) into your project dependencies. local-web-server only includes a default set; custom stacks require explicit installation.

Upgrade

Version history

5.4.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/lwsjs/local-web-server ↗

packagehttps://www.npmjs.com/package/local-web-server ↗

homepagehttps://local-web-server.com ↗