Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
createMiddleware
✓ import { createMiddleware } from 'koa-parcel-middleware'
✗ import createMiddleware from 'koa-parcel-middleware'
This is the primary named export for modern ES module environments or TypeScript projects. Attempting to use a default import will result in an undefined value.
createMiddleware (CommonJS)
✓ const { createMiddleware } = require('koa-parcel-middleware')
✗ const createMiddleware = require('koa-parcel-middleware')
For CommonJS environments, ensure you destructure the `createMiddleware` function from the module object, as it is a named export, not a default export.
KoaParcelMiddlewareOptions
✓ import { KoaParcelMiddlewareOptions } from 'koa-parcel-middleware'
This package includes TypeScript typings. If you need to type the options object passed to `createMiddleware`, import the `KoaParcelMiddlewareOptions` interface (or similar, depending on the exact export name) for strict type checking.
This example demonstrates how to set up a Koa server with `koa-parcel-middleware` to bundle and serve a UI application. It includes Parcel v1 configuration, optional server-side rendering (SSR) integration, and static asset serving using `koa-static`.
import { createMiddleware } from 'koa-parcel-middleware'
import { promises as fs } from 'fs'
import * as path from 'path'
import * as ReactDOMServer from 'react-dom/server'
import Bundler from 'parcel-bundler'
import CombinedStream from 'combined-stream'
import Koa from 'koa'
import serveStatic from 'koa-static'
// Your Parcel application's unbuilt entry point
const ENTRY_FILENAME = path.resolve(__dirname, 'index.html')
const isDev = process.env.NODE_ENV === 'development'
async function start () {
const app = new Koa()
// Your Parcel application's built entry point
const outFile = path.resolve(__dirname, 'dist', 'index.html')
const outDir = path.resolve(__dirname, 'dist')
const options = {
outDir,
outFile,
watch: isDev,
minify: !isDev,
scopeHoist: false,
hmr: isDev,
detailedReport: isDev
}
const bundler = new Bundler(ENTRY_FILENAME, options)
bundler.bundle() // Initiate Parcel bundling
const staticMiddleware = serveStatic(outDir)
const parcelMiddleware = createMiddleware({
bundler,
renderHtmlMiddleware: async (ctx, next) => {
// Optionally wire in Server-Side Rendering (SSR) here
const outFileBuffer = await fs.readFile(outFile)
const [preAppEntry, postAppEntry] = outFileBuffer.toString()
.split(/<!--.*ssr.*-->/)
ctx.status = 200
const htmlStream = new CombinedStream()
;[
preAppEntry,
ReactDOMServer.renderToNodeStream(/** Your React App component here **/ null),
postAppEntry
].map(content => htmlStream.append(content))
ctx.body = htmlStream
ctx.type = 'html'
await next()
},
staticMiddleware
})
app.use((ctx, next) => parcelMiddleware(ctx, next))
app.listen(3000, () => console.log('Koa server with Parcel middleware running on port 3000'))
}
start().catch(console.error)
Errors
Common errors & fixes
Error: Cannot find module 'koa' or 'koa-static'
One of the required peer dependencies (koa or koa-static) has not been installed.
fixRun `npm install koa koa-static` or `yarn add koa koa-static` in your project directory.
TypeError: bundler.bundle is not a function
You are likely attempting to use Parcel v2 (`parcel`) instead of Parcel v1 (`parcel-bundler`) with this middleware. Parcel v2 has a different API.
fixInstall `parcel-bundler` (Parcel v1) and ensure your code uses it: `npm install parcel-bundler` or `yarn add parcel-bundler`. Adjust `import Bundler from 'parcel-bundler'` accordingly.
TypeError: createMiddleware is not a function
This error often occurs when trying to use `require('koa-parcel-middleware')` and then directly calling it, or trying to use `import createMiddleware from 'koa-parcel-middleware'` (default import) instead of the correct named import.
fixFor CommonJS, use `const { createMiddleware } = require('koa-parcel-middleware')`. For ESM/TypeScript, use `import { createMiddleware } from 'koa-parcel-middleware'`. Audit
Dependencies
koarequiredRequired peer dependency for the Koa.js application framework.
koa-staticrequiredRequired peer dependency for serving static assets (e.g., CSS, images) built by Parcel.