{"id":15674,"library":"koa-parcel-middleware","title":"Koa Parcel Middleware","description":"koa-parcel-middleware is a Koa.js middleware designed to integrate the Parcel bundler's functionality directly into a Koa application. This enables developers to serve their UI applications from the same Koa server, leverage Parcel's development server features like Hot Module Replacement (HMR) within an existing server setup, and implement advanced techniques such as server-side rendering (SSR) for isomorphic JavaScript. The package is currently at version 1.0.3, with its last release in 2019, indicating an abandoned or unmaintained status. Its primary differentiator is the seamless integration of Parcel v1's bundling capabilities with Koa's middleware stack, obviating the need for a separate Parcel dev server process.","status":"abandoned","version":"1.0.3","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/cdaringe/koa-parcel-middleware","tags":["javascript","koa","koajs","parcel","parcel-bundler","middleware","ssr","hmr","isomorphic"],"install":[{"cmd":"npm install koa-parcel-middleware","lang":"bash","label":"npm"},{"cmd":"yarn add koa-parcel-middleware","lang":"bash","label":"yarn"},{"cmd":"pnpm add koa-parcel-middleware","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required peer dependency for the Koa.js application framework.","package":"koa","optional":false},{"reason":"Required peer dependency for serving static assets (e.g., CSS, images) built by Parcel.","package":"koa-static","optional":false}],"imports":[{"note":"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.","wrong":"import createMiddleware from 'koa-parcel-middleware'","symbol":"createMiddleware","correct":"import { createMiddleware } from 'koa-parcel-middleware'"},{"note":"For CommonJS environments, ensure you destructure the `createMiddleware` function from the module object, as it is a named export, not a default export.","wrong":"const createMiddleware = require('koa-parcel-middleware')","symbol":"createMiddleware (CommonJS)","correct":"const { createMiddleware } = require('koa-parcel-middleware')"},{"note":"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.","symbol":"KoaParcelMiddlewareOptions","correct":"import { KoaParcelMiddlewareOptions } from 'koa-parcel-middleware'"}],"quickstart":{"code":"import { createMiddleware } from 'koa-parcel-middleware'\nimport { promises as fs } from 'fs'\nimport * as path from 'path'\nimport * as ReactDOMServer from 'react-dom/server'\nimport Bundler from 'parcel-bundler'\nimport CombinedStream from 'combined-stream'\nimport Koa from 'koa'\nimport serveStatic from 'koa-static'\n\n// Your Parcel application's unbuilt entry point\nconst ENTRY_FILENAME = path.resolve(__dirname, 'index.html')\nconst isDev = process.env.NODE_ENV === 'development'\n\nasync function start () {\n  const app = new Koa()\n  // Your Parcel application's built entry point\n  const outFile = path.resolve(__dirname, 'dist', 'index.html')\n  const outDir = path.resolve(__dirname, 'dist')\n  const options = {\n    outDir,\n    outFile,\n    watch: isDev,\n    minify: !isDev,\n    scopeHoist: false,\n    hmr: isDev,\n    detailedReport: isDev\n  }\n  const bundler = new Bundler(ENTRY_FILENAME, options)\n  bundler.bundle() // Initiate Parcel bundling\n\n  const staticMiddleware = serveStatic(outDir)\n  const parcelMiddleware = createMiddleware({\n    bundler,\n    renderHtmlMiddleware: async (ctx, next) => {\n      // Optionally wire in Server-Side Rendering (SSR) here\n      const outFileBuffer = await fs.readFile(outFile)\n      const [preAppEntry, postAppEntry] = outFileBuffer.toString()\n        .split(/<!--.*ssr.*-->/)\n      ctx.status = 200\n      const htmlStream = new CombinedStream()\n      ;[\n        preAppEntry,\n        ReactDOMServer.renderToNodeStream(/** Your React App component here **/ null),\n        postAppEntry\n      ].map(content => htmlStream.append(content))\n      ctx.body = htmlStream\n      ctx.type = 'html'\n      await next()\n    },\n    staticMiddleware\n  })\n\n  app.use((ctx, next) => parcelMiddleware(ctx, next))\n  app.listen(3000, () => console.log('Koa server with Parcel middleware running on port 3000'))\n}\nstart().catch(console.error)\n","lang":"typescript","description":"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`."},"warnings":[{"fix":"Ensure you are using `parcel-bundler` (Parcel v1) in your project. If you need Parcel v2, consider alternatives or manually integrate Parcel's middleware for Koa.","message":"This middleware is designed for and implicitly relies on Parcel v1 (`parcel-bundler`). It is not compatible with Parcel v2, which introduced significant breaking API changes. Attempting to use it with Parcel v2 will lead to runtime errors due to API mismatches.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Be aware of potential compatibility issues with newer ecosystems. Consider forking the repository for custom maintenance or explore more actively maintained alternatives if long-term support is critical.","message":"The package has not been updated since July 2019, indicating it is no longer actively maintained. This means it may not receive bug fixes, security updates, or compatibility updates for newer versions of Node.js, Koa, or other dependencies.","severity":"gotcha","affected_versions":">=1.0.3"},{"fix":"Install peer dependencies: `npm install koa koa-static` or `yarn add koa koa-static`.","message":"This package lists `koa` (>=2) and `koa-static` (>=4) as peer dependencies. These must be explicitly installed in your project, otherwise, the middleware will fail to function due to missing modules.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Run `npm install koa koa-static` or `yarn add koa koa-static` in your project directory.","cause":"One of the required peer dependencies (koa or koa-static) has not been installed.","error":"Error: Cannot find module 'koa' or 'koa-static'"},{"fix":"Install `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.","cause":"You are likely attempting to use Parcel v2 (`parcel`) instead of Parcel v1 (`parcel-bundler`) with this middleware. Parcel v2 has a different API.","error":"TypeError: bundler.bundle is not a function"},{"fix":"For CommonJS, use `const { createMiddleware } = require('koa-parcel-middleware')`. For ESM/TypeScript, use `import { createMiddleware } from 'koa-parcel-middleware'`.","cause":"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.","error":"TypeError: createMiddleware is not a function"}],"ecosystem":"npm"}