{"id":17452,"library":"lws-mime","title":"lws-mime: Local Web Server MIME Type Middleware","description":"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.","status":"maintenance","version":"2.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/lwsjs/mime","tags":["javascript","lws","lws-middleware","mime"],"install":[{"cmd":"npm install lws-mime","lang":"bash","label":"npm"},{"cmd":"yarn add lws-mime","lang":"bash","label":"yarn"},{"cmd":"pnpm add lws-mime","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency; lws-mime is a middleware for the local-web-server (lws) package.","package":"lws","optional":false}],"imports":[{"note":"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`.","wrong":"import lwsMime from 'lws-mime';","symbol":"lwsMime","correct":"const lwsMime = require('lws-mime');"},{"note":"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.","wrong":"const configureLwsMime = require('lws-mime')({ /* options */ });","symbol":"configureLwsMime","correct":"const lwsMime = require('lws-mime');\n// Pass directly to lws configuration stack\n{\n  module: lwsMime,\n  options: { 'myext': 'application/x-my-format' }\n}"}],"quickstart":{"code":"const lws = require('lws');\nconst path = require('path');\nconst fs = require('fs');\n\n// Create a dummy file with a custom extension\nconst filePath = path.join(__dirname, 'example.custom');\nfs.writeFileSync(filePath, '{\"message\": \"Hello, custom world!\"}', 'utf8');\n\nconst server = lws.create({\n  stack: [\n    // lws-mime middleware to define custom MIME types\n    { module: require('lws-mime'), options: { 'custom': 'application/vnd.my-custom-format+json' } },\n    // lws-static to serve the file\n    { module: require('lws-static'), options: { root: __dirname } }\n  ],\n  port: 8000\n});\n\nserver.listen(() => {\n  console.log('Server running on http://localhost:8000');\n  console.log('Try accessing: http://localhost:8000/example.custom');\n  console.log('The response should have Content-Type: application/vnd.my-custom-format+json');\n});\n\n// Clean up dummy file on process exit\nprocess.on('exit', () => {\n  if (fs.existsSync(filePath)) {\n    fs.unlinkSync(filePath);\n  }\n});","lang":"javascript","description":"Demonstrates how to start an `lws` server, integrate `lws-mime` middleware, and define a custom MIME type for a specific file extension."},"warnings":[{"fix":"Upgrade your Node.js environment to version 10 or higher, or use an older compatible version of lws-mime (if available and suitable).","message":"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.","severity":"breaking","affected_versions":"<2.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"When defining MIME type mappings in the `lws-mime` options, ensure keys are plain file extensions (e.g., `{ 'js': 'text/javascript' }`).","message":"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.","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":"Run `npm install lws-mime` or `yarn add lws-mime` in your project directory.","cause":"The lws-mime package is not installed in your project's `node_modules`.","error":"Error: Cannot find module 'lws-mime'"},{"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')()`.","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()`.","error":"TypeError: lwsMime is not a function"},{"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`).","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`.","error":"HTTP response Content-Type header is not the expected custom MIME type."}],"ecosystem":"npm","meta_description":null}