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
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
lwsIndex
✓ import lwsIndex from 'lws-index';
✗ const lwsIndex = require('lws-index');
While CommonJS `require` might work in some Node.js environments, modern `lws` setups and `lws-index` are primarily designed for ES Modules. Use `import` for programmatic configuration.
Lws
✓ import Lws from 'lws';
✗ const Lws = require('lws');
Required for programmatic setup of the server, as `lws-index` is a middleware plugin for `lws`.
MiddlewareFactoryOptions
✓ import lwsIndex, { Options } from 'lws-index';
The `Options` type (or similar, if exported) would define the configuration object passed to `lwsIndex()` for type-safe usage in TypeScript.
This example demonstrates how to set up `lws` programmatically, configuring it with both `lws-static` to serve files and `lws-index` to provide directory listings. It creates a sample directory structure and starts a server that will show directory contents when navigating to a folder.
import Lws from 'lws';
import lwsIndex from 'lws-index';
import lwsStatic from 'lws-static';
import { createRequire } from 'module';
import path from 'path';
import { fileURLToPath } from 'url';
const __dirname = path.dirname(fileURLToPath(import.meta.url));
const require = createRequire(import.meta.url);
// Ensure a directory exists for testing
import { mkdirSync, writeFileSync } from 'fs';
const publicDir = path.join(__dirname, 'public');
mkdirSync(publicDir, { recursive: true });
writeFileSync(path.join(publicDir, 'index.html'), '<h1>Hello from Lws!</h1>');
mkdirSync(path.join(publicDir, 'subfolder'), { recursive: true });
writeFileSync(path.join(publicDir, 'subfolder', 'test.txt'), 'This is a test file.');
writeFileSync(path.join(publicDir, '.hiddenfile'), 'You should not see this by default.');
const PORT = process.env.PORT || 8000;
new Lws().listen({
port: PORT,
directory: publicDir, // This sets the default root for lws-static and lws-index
stack: [
lwsStatic(), // Serve static files first
lwsIndex({
root: publicDir, // Explicitly set the root for the index listing
hidden: false, // Do not show hidden files by default
view: 'tiles' // Use the 'tiles' display mode
})
]
}).on('started', ({ url }) => {
console.log(`Lws server with directory listing started on ${url}`);
console.log(`Try navigating to ${url}/subfolder/`);
});
Debug
Known issues
gotchaWhen using `lws-index` with `lws-static`, ensure that `lws-static` is placed before `lws-index` in the middleware stack. If `lws-index` comes first, it might intercept requests for existing files and show a directory listing instead of the file itself (if the request path matches a directory).fixOrder your middleware stack carefully: `stack: [lwsStatic(), lwsIndex()]`
affects: >=1.0.0
gotchaThe `--index.root` option (or `root` property in programmatic config) defaults to the value of `--directory` or the current working directory. If you intend to serve listings from a specific subdirectory, always explicitly set `--index.root` to avoid unexpected paths being listed.fixAlways specify `root` for `lwsIndex({ root: '/your/path' })` or `--index.root /your/path`. affects: >=1.0.0
breakingThis package requires Node.js version 12.17 or higher. Older Node.js versions are not supported and will result in runtime errors due to engine requirements.fixUpgrade your Node.js environment to version 12.17 or newer.
affects: <12.17 (Node.js)
Errors
Common errors & fixes
Error: Cannot find module 'lws'
`lws` is not installed or not resolvable in the current project.
fixInstall `lws` as a dependency: `npm install lws`
TypeError: lwsIndex is not a function
Attempting to use `require('lws-index')` in an ES Module context or incorrect import of `lwsIndex`.
fixEnsure you are using `import lwsIndex from 'lws-index';` for ES Modules and verify `lws-index` is correctly installed.
Error: listen EADDRINUSE: address already in use :::8000
Another process is already using the specified port (e.g., port 8000).
fixChange the `port` in your `listen` configuration, or terminate the conflicting process.
Audit
Dependencies
lwsrequiredCore server framework for which lws-index is a plugin.
serve-indexrequiredInternal dependency that lws-index wraps to provide directory listing functionality.