lws-spa

4.1.1 verified Sat Apr 25 auth: no javascript

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.

Common errors

error Error [ERR_REQUIRE_ESM]: require() of ES Module not supported ↓

cause Using CommonJS require() to load an ESM-only package.

fix

Use import() dynamic import or switch to ESM in your project.

error TypeError: lwsSpa is not a function ↓

cause Using named import instead of default import.

fix

import lwsSpa from 'lws-spa' instead of import { lwsSpa } from 'lws-spa'.

error Error: lws-spa: please specify the path to your SPA file via the --spa option ↓

cause The spa option was not provided when using lws-spa middleware.

fix

Add --spa app.html to your lws command line or set spa: 'app.html' in the config.

Warnings

breaking lws-spa v4 dropped support for Node.js <12.17 and lws <4. ↓

fix Update to Node.js >=12.17 and lws >=4.

breaking The --spa-asset-test-fs option replaced the deprecated --spa.asset-test-fs in v3. ↓

fix Use --spa.asset-test-fs (with dots) or the equivalent object config.

deprecated The --spa-asset-test option (without dots) is deprecated in favor of --spa.asset-test. ↓

fix Use --spa.asset-test (with dot).

gotcha If the `spa` option is not set, the middleware silently does nothing. ↓

fix Always provide the `spa` file path, e.g., --spa app.html.

gotcha 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. ↓

fix Set a more specific regex or use asset-test-fs if needed.

Install

npm install lws-spa

yarn add lws-spa

pnpm add lws-spa

Imports

default
wrong
```
const lwsSpa = require('lws-spa')
```
correct
```
import lwsSpa from 'lws-spa'
```
lws-spa is an ESM-only module since v2; CommonJS require is not supported.
lwsSpa
wrong
```
import { lwsSpa } from 'lws-spa'
```
correct
```
import lwsSpa from 'lws-spa'
```
The package exports a single default function; named import is a common mistake.

MiddlewareModule

wrong

module.exports = require('lws-spa')

correct

import lwsSpa from 'lws-spa'; export { lwsSpa as default }

When using CommonJS in lws config, use dynamic import or use ESM config.

Quickstart

Creates an lws server with SPA support using lws-spa middleware and serves app.html as fallback for all non-asset requests.

import lws from 'lws'
import lwsSpa from 'lws-spa'

const server = lws({
  stack: [lwsSpa],
  port: 8080,
  directory: './public',
  spa: 'app.html'
})

server.listen(() => {
  console.log('SPA server running on http://localhost:8080')
})