Koa Parcel Middleware

Common errors

• Error: Cannot find module 'koa' or 'koa-static'

  cause One of the required peer dependencies (koa or koa-static) has not been installed.
  fix Run `npm install koa koa-static` or `yarn add koa koa-static` in your project directory.

• TypeError: bundler.bundle is not a function

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

• TypeError: createMiddleware is not a function

  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.
  fix For CommonJS, use `const { createMiddleware } = require('koa-parcel-middleware')`. For ESM/TypeScript, use `import { createMiddleware } from 'koa-parcel-middleware'`.

Warnings

• breaking 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.
  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.
• gotcha 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.
  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.
• gotcha 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.
  Fix: Install peer dependencies: `npm install koa koa-static` or `yarn add koa koa-static`.

Install

• npm install koa-parcel-middleware npm
• yarn add koa-parcel-middleware yarn
• pnpm add koa-parcel-middleware pnpm

Imports

• createMiddleware
  wrong:

  import createMiddleware from 'koa-parcel-middleware'

  correct:

  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)
  wrong:

  const createMiddleware = require('koa-parcel-middleware')

  correct:

  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.

Quickstart

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)