Local Web Server

5.4.0 · active · verified Sun Apr 19

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.

Common errors

```
SyntaxError: Cannot use import statement outside a module
```
cause 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
```
cause 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)
```
cause 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.
```
cause 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.

Warnings

breaking local-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`.
breaking Version 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`).
breaking The 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`).
breaking In 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.
gotcha When 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.

Install

npm install local-web-server npm
yarn add local-web-server yarn
pnpm add local-web-server pnpm

Imports

createServer
wrong:
```
const createServer = require('local-web-server')
```
correct:
```
import createServer from '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.

Quickstart

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 || './'}`);

view raw JSON →