{"id":15132,"library":"koa-node-resolve","title":"Koa Node Resolve Middleware","description":"This Koa middleware dynamically rewrites Node.js bare module specifiers (e.g., `import { foo } from \"stuff\";`) into relative paths (e.g., `./node_modules/stuff/index.js`) on the fly, directly within HTML and JavaScript files served by the Koa server. It's specifically designed to facilitate modern JavaScript module development in browsers without requiring a separate build step, by resolving module paths using the same rules as Node.js `require()`. The package is currently in a pre-release state (version `1.0.0-pre.9`), indicating ongoing active development towards a stable `1.0.0` release, though no specific release cadence is published. Its key differentiator lies in its real-time, on-demand transformation capabilities, making it highly suitable for rapid iteration in development servers, integrated testing environments (such as those using Karma), and simple static file serving. However, it explicitly carries a significant caveat: it is *not* recommended for high-volume production use due to the inherent performance overhead associated with parsing and transforming HTML and JavaScript content on every request. This focus on development efficiency over production performance is a core design principle.","status":"active","version":"1.0.0-pre.9","language":"javascript","source_language":"en","source_url":"https://github.com/PolymerLabs/koa-node-resolve","tags":["javascript"],"install":[{"cmd":"npm install koa-node-resolve","lang":"bash","label":"npm"},{"cmd":"yarn add koa-node-resolve","lang":"bash","label":"yarn"},{"cmd":"pnpm add koa-node-resolve","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"This package is Koa middleware and requires Koa to function.","package":"koa","optional":false}],"imports":[{"note":"While CommonJS `require()` is shown in the quickstart, named ESM imports are the modern recommended approach for Node.js modules. The library's core function is a named export.","wrong":"const nodeResolve = require('koa-node-resolve');","symbol":"nodeResolve","correct":"import { nodeResolve } from 'koa-node-resolve';"},{"note":"This CommonJS `require()` pattern is explicitly shown in the documentation's usage examples and is fully supported for Node.js environments that do not use ESM.","symbol":"nodeResolve","correct":"const { nodeResolve } = require('koa-node-resolve');"},{"note":"This utility function is for advanced customization of HTML serialization, specifically to remove boilerplate HTML elements added by `parse5`.","symbol":"removeFakeRootElements","correct":"import { removeFakeRootElements } from 'koa-node-resolve/lib/support/parse5-utils';"}],"quickstart":{"code":"npm install --save-dev koa koa-static koa-node-resolve\n\n// dev-server.js\nconst Koa = require('koa');\nconst staticFiles = require('koa-static');\nconst { nodeResolve } = require('koa-node-resolve');\n\nconst server = new Koa()\n  .use(nodeResolve({\n    root: process.cwd(), // Important for module resolution\n    logLevel: 'debug' // See all resolution details\n  }))\n  .use(staticFiles('.'))\n  .listen(3000, () => {\n    console.log('Development server running on http://localhost:3000');\n    console.log('Access your HTML/JS files that use bare module specifiers.');\n  });\n\n// To run: node dev-server.js","lang":"javascript","description":"Sets up a basic Koa development server with `koa-node-resolve` to dynamically transform bare module specifiers in served HTML and JavaScript files to relative paths, making them runnable directly in browsers without a build step. It also includes `koa-static` for serving files."},"warnings":[{"fix":"Do not use `koa-node-resolve` in production. Implement a build step (e.g., Rollup, Webpack, esbuild) for production deployments to pre-bundle and optimize modules.","message":"This middleware is explicitly designed for development environments and testing, not for high-volume production servers. Parsing and transforming HTML/JavaScript on every request incurs significant performance overhead.","severity":"gotcha","affected_versions":">=1.0.0-pre.0"},{"fix":"Be prepared for potential API changes and breaking alterations when updating versions. Refer to the GitHub repository's commit history or pre-release changelogs for specific updates.","message":"The package is currently in a pre-release state (e.g., `1.0.0-pre.9`). This means the API is subject to change without adhering to strict semantic versioning rules until a stable `1.0.0` release.","severity":"breaking","affected_versions":">=1.0.0-pre.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Ensure `npm install --save-dev koa` is run, and `const Koa = require('koa');` is at the top of your server file, followed by `new Koa()` to create the server instance.","cause":"The `koa` package is not installed or the `Koa` class is not correctly imported/instantiated.","error":"TypeError: server.use is not a function"},{"fix":"Verify that the `root` option passed to `nodeResolve()` accurately reflects the base directory where your `node_modules` folder and served files reside. Ensure the module is actually installed and accessible from that `root`.","cause":"The `koa-node-resolve` middleware could not locate the specified bare module on the filesystem, typically because the `root` option is incorrect or the module is not in `node_modules` relative to the `root` path.","error":"Error: Cannot find module 'some-bare-specifier' (in server logs) or Failed to load module script: Expected a JavaScript module script but the server responded with a MIME type of \"text/html\". (in browser console)"},{"fix":"Ensure your Node.js environment is configured for ESM by either adding `\"type\": \"module\"` to your `package.json` or by using the `.mjs` file extension for your server file. Alternatively, stick to CommonJS `require()` syntax as shown in the package's quickstart example.","cause":"Attempting to run a server file (e.g., `dev-server.js`) that uses ES module syntax (`import`/`export`) in a CommonJS context without Node.js being configured for ESM.","error":"SyntaxError: Unexpected token 'export' or SyntaxError: Cannot use import statement outside a module"}],"ecosystem":"npm"}