{"id":17113,"library":"lws-index","title":"Lws Directory Listing Middleware","description":"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.","status":"active","version":"3.1.1","language":"javascript","source_language":"en","source_url":"https://github.com/lwsjs/index","tags":["javascript","lws","lws-middleware","index","server","backend"],"install":[{"cmd":"npm install lws-index","lang":"bash","label":"npm"},{"cmd":"yarn add lws-index","lang":"bash","label":"yarn"},{"cmd":"pnpm add lws-index","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core server framework for which lws-index is a plugin.","package":"lws","optional":false},{"reason":"Internal dependency that lws-index wraps to provide directory listing functionality.","package":"serve-index","optional":false}],"imports":[{"note":"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.","wrong":"const lwsIndex = require('lws-index');","symbol":"lwsIndex","correct":"import lwsIndex from 'lws-index';"},{"note":"Required for programmatic setup of the server, as `lws-index` is a middleware plugin for `lws`.","wrong":"const Lws = require('lws');","symbol":"Lws","correct":"import Lws from 'lws';"},{"note":"The `Options` type (or similar, if exported) would define the configuration object passed to `lwsIndex()` for type-safe usage in TypeScript.","symbol":"MiddlewareFactoryOptions","correct":"import lwsIndex, { Options } from 'lws-index';"}],"quickstart":{"code":"import Lws from 'lws';\nimport lwsIndex from 'lws-index';\nimport lwsStatic from 'lws-static';\nimport { createRequire } from 'module';\nimport path from 'path';\nimport { fileURLToPath } from 'url';\n\nconst __dirname = path.dirname(fileURLToPath(import.meta.url));\nconst require = createRequire(import.meta.url);\n\n// Ensure a directory exists for testing\nimport { mkdirSync, writeFileSync } from 'fs';\nconst publicDir = path.join(__dirname, 'public');\nmkdirSync(publicDir, { recursive: true });\nwriteFileSync(path.join(publicDir, 'index.html'), '<h1>Hello from Lws!</h1>');\nmkdirSync(path.join(publicDir, 'subfolder'), { recursive: true });\nwriteFileSync(path.join(publicDir, 'subfolder', 'test.txt'), 'This is a test file.');\nwriteFileSync(path.join(publicDir, '.hiddenfile'), 'You should not see this by default.');\n\nconst PORT = process.env.PORT || 8000;\n\nnew Lws().listen({\n  port: PORT,\n  directory: publicDir, // This sets the default root for lws-static and lws-index\n  stack: [\n    lwsStatic(), // Serve static files first\n    lwsIndex({\n      root: publicDir, // Explicitly set the root for the index listing\n      hidden: false,  // Do not show hidden files by default\n      view: 'tiles'   // Use the 'tiles' display mode\n    })\n  ]\n}).on('started', ({ url }) => {\n  console.log(`Lws server with directory listing started on ${url}`);\n  console.log(`Try navigating to ${url}/subfolder/`);\n});","lang":"typescript","description":"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."},"warnings":[{"fix":"Order your middleware stack carefully: `stack: [lwsStatic(), lwsIndex()]`","message":"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).","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always specify `root` for `lwsIndex({ root: '/your/path' })` or `--index.root /your/path`.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Upgrade your Node.js environment to version 12.17 or newer.","message":"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.","severity":"breaking","affected_versions":"<12.17 (Node.js)"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Install `lws` as a dependency: `npm install lws`","cause":"`lws` is not installed or not resolvable in the current project.","error":"Error: Cannot find module 'lws'"},{"fix":"Ensure you are using `import lwsIndex from 'lws-index';` for ES Modules and verify `lws-index` is correctly installed.","cause":"Attempting to use `require('lws-index')` in an ES Module context or incorrect import of `lwsIndex`.","error":"TypeError: lwsIndex is not a function"},{"fix":"Change the `port` in your `listen` configuration, or terminate the conflicting process.","cause":"Another process is already using the specified port (e.g., port 8000).","error":"Error: listen EADDRINUSE: address already in use :::8000"}],"ecosystem":"npm","meta_description":null}