lws-mime: Local Web Server MIME Type Middleware

2.0.0 · maintenance · verified Wed Apr 22

lws-mime is a middleware designed for the `lws` (local-web-server) ecosystem, enabling developers to customize and override default HTTP response MIME types. Currently stable at version 2.0.0, released in 2017, this package is in maintenance mode, providing a robust and tested solution without frequent updates, but relies on the actively developed `lws` core. Its primary differentiator is deep integration with `lws`, offering programmatic control over how file extensions map to MIME types, thereby ensuring web assets are served with the correct `Content-Type` headers. This is crucial for proper browser rendering and interpretation, especially for custom file formats or when standard MIME sniffing is insufficient. While other general `mime` libraries exist, lws-mime offers a tailored solution for `lws` deployments.

Common errors

```
Error: Cannot find module 'lws-mime'
```
cause The lws-mime package is not installed in your project's `node_modules`.

fix Run `npm install lws-mime` or `yarn add lws-mime` in your project directory.
```
TypeError: lwsMime is not a function
```
cause Incorrectly trying to call the `require('lws-mime')` result directly as a middleware, instead of passing it as a module object to `lws.create()`.

fix When using `lws-mime` programmatically, pass `{ module: require('lws-mime'), options: { ... } }` within the `lws` stack array, rather than attempting to call `require('lws-mime')()`.
```
HTTP response Content-Type header is not the expected custom MIME type.
```
cause This typically indicates either an incorrect configuration in `lws-mime` options (e.g., wrong extension mapping or leading dot in extension), or a middleware order issue where another middleware overwrites the `Content-Type` header set by `lws-mime`.

fix Verify that your `lws-mime` configuration uses correct, dot-less file extensions. Also, adjust the order of middleware in your `lws` stack to ensure `lws-mime` runs before other middleware that might finalize the `Content-Type` header (e.g., before `lws-static`).

Warnings

breaking lws-mime v2.0.0 dropped support for Node.js versions older than 10. Attempting to use it with unsupported Node.js versions will result in runtime errors or unexpected behavior.
Fix: Upgrade your Node.js environment to version 10 or higher, or use an older compatible version of lws-mime (if available and suitable).
gotcha The order of middleware in the `lws` stack is crucial. If `lws-mime` is placed after another middleware that explicitly sets the `Content-Type` header (e.g., `lws-static` without proper configuration), `lws-mime` may not be able to override it, leading to the default or incorrectly inferred MIME types being served.
Fix: Ensure `lws-mime` is placed earlier in the middleware stack, typically before static file serving middleware, to allow it to modify the `Content-Type` header before it's finalized by downstream middleware.
gotcha Configuring `lws-mime` requires specifying file extensions without the leading dot (e.g., 'json' instead of '.json'). Incorrectly including the dot will prevent the MIME type from being applied.
Fix: When defining MIME type mappings in the `lws-mime` options, ensure keys are plain file extensions (e.g., `{ 'js': 'text/javascript' }`).

Install

npm install lws-mime npm
yarn add lws-mime yarn
pnpm add lws-mime pnpm

Imports

lwsMime
wrong:
```
import lwsMime from 'lws-mime';
```
correct:
```
const lwsMime = require('lws-mime');
```
The lws-mime package primarily uses CommonJS syntax, typical for the lws ecosystem and its Node.js >=10 engine requirement. While ESM imports might technically work with bundlers, direct usage in Node.js should use `require`.
configureLwsMime
wrong:
```
const configureLwsMime = require('lws-mime')({ /* options */ });
```
correct:
```
const lwsMime = require('lws-mime');
// Pass directly to lws configuration stack
{
  module: lwsMime,
  options: { 'myext': 'application/x-my-format' }
}
```
lws-mime exports a function that takes options and returns the actual Koa-style middleware function. When integrating with lws, you typically pass the module itself along with its configuration options within the lws stack array.

Quickstart

Demonstrates how to start an `lws` server, integrate `lws-mime` middleware, and define a custom MIME type for a specific file extension.

const lws = require('lws');
const path = require('path');
const fs = require('fs');

// Create a dummy file with a custom extension
const filePath = path.join(__dirname, 'example.custom');
fs.writeFileSync(filePath, '{"message": "Hello, custom world!"}', 'utf8');

const server = lws.create({
  stack: [
    // lws-mime middleware to define custom MIME types
    { module: require('lws-mime'), options: { 'custom': 'application/vnd.my-custom-format+json' } },
    // lws-static to serve the file
    { module: require('lws-static'), options: { root: __dirname } }
  ],
  port: 8000
});

server.listen(() => {
  console.log('Server running on http://localhost:8000');
  console.log('Try accessing: http://localhost:8000/example.custom');
  console.log('The response should have Content-Type: application/vnd.my-custom-format+json');
});

// Clean up dummy file on process exit
process.on('exit', () => {
  if (fs.existsSync(filePath)) {
    fs.unlinkSync(filePath);
  }
});

view raw JSON →