{"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,"search_vec":"'5.4.0':63 'address':67 'allow':95 'api':52 'applic':45,115 'back':108 'back-end':107 'behavior':101 'box':57 'bug':68 'bundl':30 'command':84 'command-lin':83 'comprehens':103 'cor':49,131 'core':26 'current':59 'design':14,94 'dev':123 'develop':20,130 'differenti':88 'distribut':23 'enabl':37 'end':109,114,129 'featur':72,104 'file':42 'fix':69 'footprint':92 'front':113,128 'front-end':112,127 'full':18 'full-stack':17 'function':38 'http':75 'http2':78 'https':76 'includ':89 'interfac':86 'javascript':122 'key':87 'lean':10 'like':39 'line':85 'load':98 'local':1,5 'local-web-serv':4 'lws':27 'middlewar':36 'mime':132 'mock':51 'modular':11,93 'new':71 'newer':121 'node.js':118 'offer':79 'out-of-the-box':53 'pack':33 'packag':28 'page':44 'programmat':81 'prototyp':106 'rapid':16 'regular':65 'requir':100,117 'rewrit':48 'serv':40 'server':3,7,13,124 'servic':110 'singl':43 'small':91 'spas':46 'stabl':60 'stack':19 'starter':32 'static':41 'support':74 'tool':126 'updat':66 'url':47 'use':35 'user':96 'v12.20':119 'version':61 'web':2,6,12,125","created_at":"2026-04-19T13:36:59.599072+00:00","updated_at":"2026-04-19T13:36:59.599072+00:00","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","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"ws","cli_version":null,"type":"library","homepage":"https://local-web-server.com","github":"https://github.com/lwsjs/local-web-server","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/local-web-server","openapi_spec":null,"status_page":null,"smithery":null,"categories":["web-framework","http-networking"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-18","install_tag":null}}