Koa Node Resolve Middleware

1.0.0-pre.9 · active · verified Tue Apr 21

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.

Common errors

```
TypeError: server.use is not a function
```
cause The `koa` package is not installed or the `Koa` class is not correctly imported/instantiated.

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.
```
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)
```
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.

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`.
```
SyntaxError: Unexpected token 'export' or SyntaxError: Cannot use import statement outside a module
```
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.

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.

Warnings

gotcha 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.
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.
breaking 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.
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.

Install

npm install koa-node-resolve npm
yarn add koa-node-resolve yarn
pnpm add koa-node-resolve pnpm

Imports

nodeResolve
wrong:
```
const nodeResolve = require('koa-node-resolve');
```
correct:
```
import { nodeResolve } from 'koa-node-resolve';
```
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.
nodeResolve
```
const { nodeResolve } = require('koa-node-resolve');
```
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.
removeFakeRootElements
```
import { removeFakeRootElements } from 'koa-node-resolve/lib/support/parse5-utils';
```
This utility function is for advanced customization of HTML serialization, specifically to remove boilerplate HTML elements added by `parse5`.

Quickstart

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.

npm install --save-dev koa koa-static koa-node-resolve

// dev-server.js
const Koa = require('koa');
const staticFiles = require('koa-static');
const { nodeResolve } = require('koa-node-resolve');

const server = new Koa()
  .use(nodeResolve({
    root: process.cwd(), // Important for module resolution
    logLevel: 'debug' // See all resolution details
  }))
  .use(staticFiles('.'))
  .listen(3000, () => {
    console.log('Development server running on http://localhost:3000');
    console.log('Access your HTML/JS files that use bare module specifiers.');
  });

// To run: node dev-server.js

view raw JSON →