Lws Directory Listing Middleware

3.1.1 · active · verified Wed Apr 22

lws-index is a middleware plugin designed for the Lightweight Web Server (lws) ecosystem, enabling the serving of directory listings. It functions as a wrapper around the popular `serve-index` library, integrating its capabilities seamlessly into lws. The current stable version is 3.1.1, and being part of the lws family, it generally follows the lws release cadence, focusing on stability and compatibility within that ecosystem. Its key differentiator is its straightforward integration as a plugin for lws, providing configurable options like specifying a root directory, showing hidden files, and choosing between 'tiles' or 'details' view modes, without needing manual Express.js-style middleware setup. It is often used in conjunction with `lws-static` for comprehensive file serving.

Common errors

```
Error: Cannot find module 'lws'
```
cause `lws` is not installed or not resolvable in the current project.

fix Install `lws` as a dependency: `npm install lws`
```
TypeError: lwsIndex is not a function
```
cause Attempting to use `require('lws-index')` in an ES Module context or incorrect import of `lwsIndex`.

fix Ensure 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
```
cause Another process is already using the specified port (e.g., port 8000).

fix Change the `port` in your `listen` configuration, or terminate the conflicting process.

Warnings

gotcha When 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).
Fix: Order your middleware stack carefully: `stack: [lwsStatic(), lwsIndex()]`
gotcha The `--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.
Fix: Always specify `root` for `lwsIndex({ root: '/your/path' })` or `--index.root /your/path`.
breaking This 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.
Fix: Upgrade your Node.js environment to version 12.17 or newer.

Install

npm install lws-index npm
yarn add lws-index yarn
pnpm add lws-index pnpm

Imports

lwsIndex
wrong:
```
const lwsIndex = require('lws-index');
```
correct:
```
import lwsIndex from '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
wrong:
```
const Lws = require('lws');
```
correct:
```
import Lws from '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.

Quickstart

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/`);
});

view raw JSON →