lws-spa

library4.1.1jsnpmunverified

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.

web-framework

npm install lws-spa

github ↗package ↗

INSTALL

IMPORT

SIG · LWS-SPA

lws-spa

web-frameworkjavascriptv4.1.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

default

✓ import lwsSpa from 'lws-spa'

✗ const lwsSpa = require('lws-spa')

lws-spa is an ESM-only module since v2; CommonJS require is not supported.

lwsSpa

✓ import lwsSpa from 'lws-spa'

✗ import { lwsSpa } from 'lws-spa'

The package exports a single default function; named import is a common mistake.

MiddlewareModule

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

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

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

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') })

lws --version

Debug

Known issues

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

fix

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

affects: >=4.0.0 <4.1.0

breakingThe --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.

affects: >=3.0.0 <3.0.0

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

fix

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

affects: >=3.0.0

gotchaIf the `spa` option is not set, the middleware silently does nothing.

fix

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

affects: >=1.0.0

gotchaThe 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.

affects: >=1.0.0

Errors

Common errors & fixes

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

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

fix

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

TypeError: lwsSpa is not a function

Using named import instead of default import.

fix

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

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

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.

Upgrade

Version history

4.1.1latest on npm

Audit

Dependencies

lwsrequiredlws-spa is a plugin for lws; it requires lws to be installed and loaded as middleware.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/lwsjs/spa ↗

packagehttps://www.npmjs.com/package/lws-spa ↗