{"id":16431,"library":"lws-range","title":"lws-range: HTTP Range Request Middleware for lws","description":"This package, `lws-range`, is a middleware plugin designed for the `local-web-server` (`lws`) ecosystem, specifically adding robust support for HTTP Range Requests. It effectively wraps the `koa-range` library to integrate this functionality seamlessly into `lws` servers. As of version 4.0.1, it provides compliant handling of partial content requests, enabling clients to request specific byte ranges of a resource, which is crucial for features like video streaming, large file downloads with resume capabilities, and efficient caching. The project appears to be actively maintained, indicated by recent version releases and continuous integration. Its primary differentiator is its deep integration with the `lws` server, providing a simple `--stack` activation for this common HTTP feature without needing to manually configure low-level range request parsing. It mandates Node.js version 12.17 or higher.","status":"active","version":"4.0.1","language":"javascript","source_language":"en","source_url":"https://github.com/lwsjs/range","tags":["javascript","lws","lws-middleware","range","request"],"install":[{"cmd":"npm install lws-range","lang":"bash","label":"npm"},{"cmd":"yarn add lws-range","lang":"bash","label":"yarn"},{"cmd":"pnpm add lws-range","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Host server for the middleware. Required for lws-range to function.","package":"lws","optional":false},{"reason":"Underlying library wrapped by lws-range for handling range requests.","package":"koa-range","optional":false}],"imports":[{"note":"The package exports a default middleware function, not named exports. Primarily used by `lws` internally or via its CLI `--stack` option.","wrong":"import { lwsRange } from 'lws-range';","symbol":"lwsRange","correct":"import lwsRange from 'lws-range';"},{"note":"CommonJS require is supported, as the package's `package.json` uses `\"main\": \"index.js\"` and does not declare `\"type\": \"module\"`.","symbol":"lwsRange","correct":"const lwsRange = require('lws-range');"}],"quickstart":{"code":"import lws from 'lws';\nimport lwsRange from 'lws-range';\nimport lwsStatic from 'lws-static'; // Assuming lws-static is also installed\nimport { resolve } from 'path';\nimport { writeFileSync, mkdirSync } from 'fs';\n\nconst publicDir = resolve(__dirname, './public');\nmkdirSync(publicDir, { recursive: true });\n\n// Create a sample large file for testing range requests\nconst largeFilePath = resolve(publicDir, 'large-file.txt');\nconst dummyContent = 'This is a sample text file to demonstrate HTTP Range requests. '.\n  repeat(100) + 'It should be sufficiently long to make range requests meaningful.';\nwriteFileSync(largeFilePath, dummyContent);\n\n// Create a simple lws server with range request support and static file serving\nconst server = lws.create({\n  // The middleware stack defines the order of processing\n  stack: [\n    // lws-range must come before lws-static to handle range requests for static files\n    lwsRange(), \n    lwsStatic({ \n      root: publicDir, // Serve files from the 'public' directory\n      index: ['index.html', 'index.htm'] // Specify default index files\n    })\n  ],\n  port: process.env.PORT ?? 8000 // Listen on port 8000 or specified by env var\n});\n\nserver.listen(server.port, () => {\n  console.log(`lws server with range support listening on http://localhost:${server.port}`);\n  console.log('To test, create a file named ' + largeFilePath + ' (or use the one created by this script).');\n  console.log('Then try sending a curl request with a Range header, e.g.,');\n  console.log(`curl -I -H \"Range: bytes=0-100\" http://localhost:${server.port}/large-file.txt`);\n  console.log(`curl -H \"Range: bytes=0-10\" http://localhost:${server.port}/large-file.txt`);\n});","lang":"typescript","description":"Sets up an `lws` server programmatically with `lws-range` and `lws-static` middleware, demonstrating how to enable HTTP Range Request support for static files. Includes setup for a test file."},"warnings":[{"fix":"Review your `lws` configuration and `lws-range` usage. If you relied on `koa-range` specific options, they are no longer directly exposed through `lws-range` and you may need to find `lws`-specific alternatives or adjust expectations.","message":"`lws-range` v3.x removed the ability to pass options directly to the underlying `koa-range` library. Configuration for range handling must now be managed at the `lws` framework level or via environment variables if supported by `lws` itself.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Ensure your `lws` package is updated to version 5.x or later. Run `npm install lws@latest` or `yarn add lws@latest` to upgrade your `local-web-server` dependency.","message":"`lws-range` v4.x requires `lws` (local-web-server) v5.x or higher due to significant API changes in the `lws` core that this middleware integrates with.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Adjust the `stack` array in your `lws` configuration (or `--stack` CLI argument) to ensure `lwsRange()` appears earlier than `lwsStatic()` or similar static file handlers.","message":"For HTTP Range Requests to function correctly, the `lws-range` middleware must be placed *before* any static file serving middleware (e.g., `lws-static`) in the `lws` stack. If placed incorrectly, static files may be served in their entirety without honoring range headers.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Verify the `Range` header sent by the client. Ensure the requested start and end bytes are valid and within the actual file's length. This error can also occur if the resource does not exist.","cause":"The client requested a byte range that is invalid, out of bounds, or exceeds the file size of the resource being served.","error":"HTTP/1.1 416 Range Not Satisfiable"},{"fix":"Ensure you are calling `lwsRange()` (with parentheses) when adding it to the `lws` stack, e.g., `stack: [lwsRange(), ...]` for programmatic usage or ensure the CLI option is correctly formatted.","cause":"`lws-range` was not correctly imported or called as a function when added to the `lws` stack, typically meaning it was passed as `lwsRange` instead of `lwsRange()`.","error":"Error: Middleware must be a function."},{"fix":"Verify that `lws-range` is included in your `lws` stack and that its position is correct (e.g., before `lws-static`). Check for other middleware that might modify or remove the `Accept-Ranges` header.","cause":"The `lws-range` middleware is either not loaded in the `lws` stack, is placed incorrectly after a static file handler, or another middleware is interfering with HTTP headers.","error":"Missing 'Accept-Ranges: bytes' header in response."}],"ecosystem":"npm"}