Performance Engineering: Optimizing Next.js Bundle Size for Cloudflare Workers

The `handler.mjs` is 14.5 MiB uncompressed, gzipping to **3.6 MiB** — just over the free plan's 3 MiB limit. Three fixes later, the bundle is **2.0 MiB** gzipped, deployed, and running fine.

Here is exactly what I did.

---

## Why is a blog Worker so large?

The site is a standard Next.js App Router blog: all post pages are statically generated via `generateStaticParams`, served through OpenNext's `staticAssetsIncrementalCache`. The Worker should just be a thin router that serves pre-rendered HTML.

Instead, the Worker bundle contained:

- **`codehike` + `shiki`** — syntax highlighting with full TextMate language grammars
- **`next-mdx-remote`** — MDX compilation pipeline with `unified`, `acorn`, `vfile`
- **`@vercel/og`** — OG image generation including two WASM binaries, pulled in by Next.js even though the site has zero dynamic OG images
- **`gray-matter`** — frontmatter parsing, needed only at build time

All of these are build-time tools. At request time, the Worker only needs to serve the already-compiled HTML. But the webpack bundler doesn't know that — it includes everything that is imported anywhere in the codebase.

---

## Fix 1 — Tell the bundler which packages are build-time only

Next.js has a `serverExternalPackages` config that opts packages out of automatic bundling. When OpenNext compiles the Cloudflare Worker, it respects this list and excludes those packages from the Worker script.

```typescript
// next.config.ts
const nextConfig: NextConfig = {
  serverExternalPackages: [
    'next-mdx-remote',
    'codehike',
    'shiki',
    '@shikijs/core',
    '@shikijs/engine-oniguruma',
    '@shikijs/vscode-textmate',
    'rehype-slug',
    'remark-gfm',
    'gray-matter',
    'unified',
    'vfile',
    'acorn',
    'esprima',
  ],
  // ...
}

▲ [WARNING] Using direct eval with a bundler is not recommended [direct-eval]
    .open-next/server-functions/default/handler.mjs:241:8
▲ [WARNING] Using direct eval with a bundler is not recommended [direct-eval]
    .open-next/server-functions/default/handler.mjs:20601:8

// next.config.ts
webpack: (config) => {
  config.resolve.alias = {
    ...config.resolve.alias,
    'next/og': false,
  }
  return config
},

// src/app/blog/[slug]/page.tsx  — before
export async function generateStaticParams() { ... }

// src/app/blog/[slug]/page.tsx  — after
export const dynamic = 'force-static'
export const revalidate = false
export const dynamicParams = false  // unknown slugs → 404, not a Worker render attempt

export async function generateStaticParams() { ... }

⨯ ERROR: This build is using Turbopack, with a `webpack` config and no `turbopack` config.
  This may be a mistake.

// next.config.ts
const nextConfig: NextConfig = {
  turbopack: {}, // dev uses Turbopack — no custom config needed

  webpack: config => {
    // only runs during `next build`, not `next dev`
    config.resolve.alias = {
      ...config.resolve.alias,
      'next/og': false,
    }
    return config
  },
}

import type { NextConfig } from 'next'
import { initOpenNextCloudflareForDev } from '@opennextjs/cloudflare'

const nextConfig: NextConfig = {
  pageExtensions: ['js', 'jsx', 'ts', 'tsx'],

  serverExternalPackages: [
    'next-mdx-remote',
    'codehike',
    'shiki',
    '@shikijs/core',
    '@shikijs/engine-oniguruma',
    '@shikijs/vscode-textmate',
    'rehype-slug',
    'remark-gfm',
    'gray-matter',
    'unified',
    'vfile',
    'acorn',
    'esprima',
  ],

  turbopack: {},

  webpack: config => {
    config.resolve.alias = {
      ...config.resolve.alias,
      'next/og': false,
    }
    return config
  },

  images: {
    remotePatterns: [{ protocol: 'https', hostname: 'example.com', pathname: '/**' }],
  },
}

initOpenNextCloudflareForDev()
export default nextConfig