{"id":18520,"library":"lws-spa","title":"lws-spa","description":"lws-spa is a middleware plugin for lws (local-web-server) that adds Single Page Application support. As of version 4.1.1 (stable, active maintenance), it allows you to serve a SPA by providing a fallback file (e.g., app.html) that is returned for non-asset requests, with configurable asset detection using regular expressions or filesystem checks. It integrates seamlessly into lws's plugin architecture and is updated occasionally; the package is part of the lws ecosystem and targets Node.js >=12.17. Compared to generic static file servers, lws-spa provides SPA-specific options like asset testing via regex or filesystem, making it a focused solution for SPA development.","status":"active","version":"4.1.1","language":"javascript","source_language":"en","source_url":"https://github.com/lwsjs/spa","tags":["javascript","lws","lws-middleware","spa"],"install":[{"cmd":"npm install lws-spa","lang":"bash","label":"npm"},{"cmd":"yarn add lws-spa","lang":"bash","label":"yarn"},{"cmd":"pnpm add lws-spa","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"lws-spa is a plugin for lws; it requires lws to be installed and loaded as middleware.","package":"lws","optional":false}],"imports":[{"note":"lws-spa is an ESM-only module since v2; CommonJS require is not supported.","wrong":"const lwsSpa = require('lws-spa')","symbol":"default","correct":"import lwsSpa from 'lws-spa'"},{"note":"The package exports a single default function; named import is a common mistake.","wrong":"import { lwsSpa } from 'lws-spa'","symbol":"lwsSpa","correct":"import lwsSpa from 'lws-spa'"},{"note":"When using CommonJS in lws config, use dynamic import or use ESM config.","wrong":"module.exports = require('lws-spa')","symbol":"MiddlewareModule","correct":"import lwsSpa from 'lws-spa'; export { lwsSpa as default }"}],"quickstart":{"code":"import lws from 'lws'\nimport lwsSpa from 'lws-spa'\n\nconst server = lws({\n  stack: [lwsSpa],\n  port: 8080,\n  directory: './public',\n  spa: 'app.html'\n})\n\nserver.listen(() => {\n  console.log('SPA server running on http://localhost:8080')\n})","lang":"typescript","description":"Creates an lws server with SPA support using lws-spa middleware and serves app.html as fallback for all non-asset requests."},"warnings":[{"fix":"Update to Node.js >=12.17 and lws >=4.","message":"lws-spa v4 dropped support for Node.js <12.17 and lws <4.","severity":"breaking","affected_versions":">=4.0.0 <4.1.0"},{"fix":"Use --spa.asset-test-fs (with dots) or the equivalent object config.","message":"The --spa-asset-test-fs option replaced the deprecated --spa.asset-test-fs in v3.","severity":"breaking","affected_versions":">=3.0.0 <3.0.0"},{"fix":"Use --spa.asset-test (with dot).","message":"The --spa-asset-test option (without dots) is deprecated in favor of --spa.asset-test.","severity":"deprecated","affected_versions":">=3.0.0"},{"fix":"Always provide the `spa` file path, e.g., --spa app.html.","message":"If the `spa` option is not set, the middleware silently does nothing.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Set a more specific regex or use asset-test-fs if needed.","message":"The asset-test regex defaults to '.' (any character), meaning any request containing a dot is treated as an asset file. This may incorrectly match routes with dots.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-25T00:00:00.000Z","next_check":"2026-07-24T00:00:00.000Z","problems":[{"fix":"Use import() dynamic import or switch to ESM in your project.","cause":"Using CommonJS require() to load an ESM-only package.","error":"Error [ERR_REQUIRE_ESM]: require() of ES Module not supported"},{"fix":"import lwsSpa from 'lws-spa' instead of import { lwsSpa } from 'lws-spa'.","cause":"Using named import instead of default import.","error":"TypeError: lwsSpa is not a function"},{"fix":"Add `--spa app.html` to your lws command line or set `spa: 'app.html'` in the config.","cause":"The spa option was not provided when using lws-spa middleware.","error":"Error: lws-spa: please specify the path to your SPA file via the --spa option"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}