{"id":11246,"library":"local-web-server","title":"Local Web Server","description":"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.","status":"active","version":"5.4.0","language":"javascript","source_language":"en","source_url":"https://github.com/lwsjs/local-web-server","tags":["javascript","dev","server","web","tool","front-end","development","cors","mime"],"install":[{"cmd":"npm install local-web-server","lang":"bash","label":"npm"},{"cmd":"yarn add local-web-server","lang":"bash","label":"yarn"},{"cmd":"pnpm add local-web-server","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"const createServer = require('local-web-server')","symbol":"createServer","correct":"import createServer from 'local-web-server'"},{"note":"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.","symbol":"ServerOptions","correct":"import type { LwsOptions } from 'lws'"},{"note":"The primary way to use local-web-server is via its command-line interface, `ws`. `npx` is recommended to run the local package executable.","symbol":"CLI 'ws' command","correct":"npx ws [options]"}],"quickstart":{"code":"import createServer from 'local-web-server';\n\n// Create a server instance with common development features\nconst server = createServer({\n  port: process.env.PORT ? parseInt(process.env.PORT) : 8000,\n  // Serve static files from the current directory\n  // local-web-server includes static serving by default if 'root' is not specified.\n  // This explicitly sets the root to the 'public' directory if it exists.\n  root: './public',\n  // Enable Single Page Application (SPA) routing, redirecting all non-file requests to index.html\n  spa: 'index.html',\n  // Enable CORS for all origins, useful for local development with separate API servers\n  cors: true,\n  // Rewrite API requests to a remote backend\n  rewrite: {\n    '/api/(.*)': 'https://jsonplaceholder.typicode.com/$1'\n  },\n  // Display a QR code in the terminal for easy mobile access\n  qr: true,\n  // Log requests in 'dev' format\n  log: 'dev'\n});\n\nserver.start();\nconsole.log(`Local Web Server running at http://localhost:${server.port}`);\nconsole.log(`Serving static files from: ${server.options.root || './'}`);","lang":"typescript","description":"This quickstart demonstrates programmatically configuring a local web server for SPA routing, API rewriting, CORS, and logging."},"warnings":[{"fix":"Upgrade Node.js to v12.20 or newer. Check your `node` version with `node -v`.","message":"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.","severity":"breaking","affected_versions":">=5.0.0"},{"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`).","message":"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.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Always use the full `lws-` prefixed name for middleware plugins (e.g., `--stack lws-static`).","message":"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.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"For WebSockets, implement a custom middleware. Consult the `lws` wiki for examples on creating middleware for specific functionalities.","message":"In v3.0.0, the `--websocket` and `--server` options were removed. WebSocket support now requires implementing it via a middleware plugin.","severity":"breaking","affected_versions":">=3.0.0 <5.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<5.4.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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+.","cause":"Attempting to `import` local-web-server in a CommonJS (`.js` without `\"type\": \"module\"` or `.cjs`) file after v5.0.0 removed CommonJS support.","error":"SyntaxError: Cannot use import statement outside a module"},{"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.","cause":"Another process is already using the specified port (default is 8000), or a previous instance of the server was not properly shut down.","error":"Error: listen EADDRINUSE: address already in use :::8000"},{"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.","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.","error":"404 Not Found (for client-side routes in a Single Page Application)"},{"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.","cause":"A custom middleware plugin was specified without being installed as a dependency in the project.","error":"ERR_MODULE_NOT_FOUND: Cannot find module 'lws-static' from '...' when using a custom stack."}],"ecosystem":"npm"}