Mark bun builtin modules as external (fixes #75220) (#77616)

Fixes #75220

This marks Bun's builtin modules as external, following the same pattern
as for Node.

- `"bun:ffi"`
- `"bun:jsc"`
- `"bun:sqlite"`
- `"bun:test"`
- `"bun:wrap"`
- `"bun"`

I have not manually tested this change yet, nor attempted to write tests
for this. I did check for other places in the code that should be
updated and _maybe_
`externals/crates/next-custom-transforms/src/transforms/warn_for_edge_runtime.rs`
should as well, but I'll leave that up to you whether or not that makes
sense. Opening as a draft until this can be at least manually tested.

By the way, node's `sqlite` module is missing from `NODE_EXTERNALS`.
That seemed out of scope but worth mentioning.

Current error message:

![image](https://github.com/user-attachments/assets/0538fd35-a1ce-44fe-af7f-1db696cd3e7b)

---------

Co-authored-by: Alistair Smith <hi@alistair.sh>

Author: Jarred-Sumner

packages/next/src/build/handle-externals.ts

@@ -188,6 +188,11 @@ export function makeExternalHandler({
         return `commonjs ${request}`
       }
 
+      // Handle Bun builtins as external modules
+      if (request === 'bun' || request.startsWith('bun:')) {
+        return `commonjs ${request}`
+      }
+
       const notExternalModules =
         /^(?:private-next-pages\/|next\/(?:dist\/pages\/|(?:app|cache|document|link|form|head|image|legacy\/image|constants|dynamic|script|navigation|headers|router|compat\/router|server)$)|string-hash|private-next-rsc-action-validate|private-next-rsc-action-client-wrapper|private-next-rsc-server-reference|private-next-rsc-cache-wrapper|private-next-rsc-track-dynamic-import$)/
       if (notExternalModules.test(request)) {

packages/next/src/build/webpack-config.ts

@@ -913,6 +913,15 @@ export default async function getBaseWebpackConfig(
   const builtinModules = (require('module') as typeof import('module'))
     .builtinModules
 
+  const bunExternals = [
+    'bun:ffi',
+    'bun:jsc',
+    'bun:sqlite',
+    'bun:test',
+    'bun:wrap',
+    'bun',
+  ]
+
   const shouldEnableSlowModuleDetection =
     !!config.experimental.slowModuleDetection && dev
 
@@ -986,6 +995,7 @@ export default async function getBaseWebpackConfig(
           ]
         : [
             ...builtinModules,
+            ...bunExternals,
             ({
               context,
               request,

packages/next/src/build/webpack/plugins/middleware-plugin.ts

@@ -288,6 +288,10 @@ function isNodeJsModule(moduleName: string) {
   )
 }
 
+function isBunModule(moduleName: string) {
+  return moduleName === 'bun' || moduleName.startsWith('bun:')
+}
+
 function isDynamicCodeEvaluationAllowed(
   fileName: string,
   middlewareConfig?: MiddlewareConfig,
@@ -521,12 +525,13 @@ function getCodeAnalyzer(params: {
 
         if (
           !dev &&
-          isNodeJsModule(importedModule) &&
+          (isNodeJsModule(importedModule) || isBunModule(importedModule)) &&
           !SUPPORTED_NATIVE_MODULES.includes(importedModule)
         ) {
+          const isBun = isBunModule(importedModule)
           compilation.warnings.push(
             buildWebpackError({
-              message: `A Node.js module is loaded ('${importedModule}' at line ${node.loc.start.line}) which is not supported in the Edge Runtime.
+              message: `A ${isBun ? 'Bun' : 'Node.js'} module is loaded ('${importedModule}' at line ${node.loc.start.line}) which is not supported in the Edge Runtime.
 Learn More: https://nextjs.org/docs/messages/node-module-in-edge-runtime`,
               compilation,
               parser,
@@ -921,7 +926,7 @@ export async function handleWebpackExternalForEdgeRuntime({
   if (
     (contextInfo.issuerLayer === WEBPACK_LAYERS.middleware ||
       contextInfo.issuerLayer === WEBPACK_LAYERS.apiEdge) &&
-    isNodeJsModule(request) &&
+    (isNodeJsModule(request) || isBunModule(request)) &&
     !supportedEdgePolyfills.has(request)
   ) {
     // allows user to provide and use their polyfills, as we do with buffer.

test/e2e/app-dir/bun-externals/app/api/bun-externals/route.ts

@@ -0,0 +1,29 @@
+import { NextResponse } from 'next/server'
+
+export async function GET() {
+  const results: Record<string, string> = {}
+
+  const modules = [
+    { name: 'bunFfi', module: 'bun:ffi' },
+    { name: 'bunJsc', module: 'bun:jsc' },
+    { name: 'bunSqlite', module: 'bun:sqlite' },
+    { name: 'bunTest', module: 'bun:test' },
+    { name: 'bunWrap', module: 'bun:wrap' },
+    { name: 'bun', module: 'bun' },
+  ]
+
+  for (const { name, module } of modules) {
+    try {
+      require(module)
+      results[name] = 'loaded'
+    } catch (e: any) {
+      // Expected: Cannot find module error when not in Bun runtime
+      // This confirms the module was externalized (not bundled)
+      results[name] = e.message.includes('Cannot find module')
+        ? 'external'
+        : 'error'
+    }
+  }
+
+  return NextResponse.json(results)
+}

test/e2e/app-dir/bun-externals/app/api/edge-bun-externals/route.ts

@@ -0,0 +1,26 @@
+import { NextResponse } from 'next/server'
+
+export const runtime = 'edge'
+
+// Edge runtime should not allow Bun imports
+// This test verifies that Bun modules are handled correctly in edge runtime
+export async function GET() {
+  const modules = [
+    { name: 'bunFfi', module: 'bun:ffi' },
+    { name: 'bunJsc', module: 'bun:jsc' },
+    { name: 'bunSqlite', module: 'bun:sqlite' },
+    { name: 'bunTest', module: 'bun:test' },
+    { name: 'bunWrap', module: 'bun:wrap' },
+    { name: 'bun', module: 'bun' },
+  ]
+
+  try {
+    for (const { module } of modules) {
+      await import(module)
+    }
+
+    return NextResponse.json('Did not throw')
+  } catch (e) {
+    return NextResponse.json(String(e))
+  }
+}

test/e2e/app-dir/bun-externals/app/layout.tsx

@@ -0,0 +1,11 @@
+export default function RootLayout({
+  children,
+}: {
+  children: React.ReactNode
+}) {
+  return (
+    <html lang="en">
+      <body>{children}</body>
+    </html>
+  )
+}

test/e2e/app-dir/bun-externals/app/page.tsx

@@ -0,0 +1,77 @@
+export default function Page() {
+  // These should be handled as external modules
+  // When not running in Bun, require() will throw "Cannot find module"
+  let bunFfiStatus = 'not loaded'
+  let bunJscStatus = 'not loaded'
+  let bunSqliteStatus = 'not loaded'
+  let bunTestStatus = 'not loaded'
+  let bunWrapStatus = 'not loaded'
+  let bunStatus = 'not loaded'
+
+  try {
+    require('bun:ffi')
+    bunFfiStatus = 'loaded successfully'
+  } catch (e: any) {
+    // Expected error when not running in Bun
+    bunFfiStatus = e.message.includes('Cannot find module')
+      ? 'external (not found)'
+      : 'error: ' + e.message
+  }
+
+  try {
+    require('bun:jsc')
+    bunJscStatus = 'loaded successfully'
+  } catch (e: any) {
+    bunJscStatus = e.message.includes('Cannot find module')
+      ? 'external (not found)'
+      : 'error: ' + e.message
+  }
+
+  try {
+    require('bun:sqlite')
+    bunSqliteStatus = 'loaded successfully'
+  } catch (e: any) {
+    bunSqliteStatus = e.message.includes('Cannot find module')
+      ? 'external (not found)'
+      : 'error: ' + e.message
+  }
+
+  try {
+    require('bun:test')
+    bunTestStatus = 'loaded successfully'
+  } catch (e: any) {
+    bunTestStatus = e.message.includes('Cannot find module')
+      ? 'external (not found)'
+      : 'error: ' + e.message
+  }
+
+  try {
+    require('bun:wrap')
+    bunWrapStatus = 'loaded successfully'
+  } catch (e: any) {
+    bunWrapStatus = e.message.includes('Cannot find module')
+      ? 'external (not found)'
+      : 'error: ' + e.message
+  }
+
+  try {
+    require('bun')
+    bunStatus = 'loaded successfully'
+  } catch (e: any) {
+    bunStatus = e.message.includes('Cannot find module')
+      ? 'external (not found)'
+      : 'error: ' + e.message
+  }
+
+  return (
+    <div>
+      <h1>Bun Externals Test</h1>
+      <div id="bun-ffi">{bunFfiStatus}</div>
+      <div id="bun-jsc">{bunJscStatus}</div>
+      <div id="bun-sqlite">{bunSqliteStatus}</div>
+      <div id="bun-test">{bunTestStatus}</div>
+      <div id="bun-wrap">{bunWrapStatus}</div>
+      <div id="bun">{bunStatus}</div>
+    </div>
+  )
+}

test/e2e/app-dir/bun-externals/app/server-action/actions.ts

@@ -0,0 +1,33 @@
+'use server'
+
+export async function testBunExternals() {
+  const modules = [
+    'bun:ffi',
+    'bun:jsc',
+    'bun:sqlite',
+    'bun:test',
+    'bun:wrap',
+    'bun',
+  ]
+  const results: Record<string, string> = {}
+
+  for (const mod of modules) {
+    try {
+      require(mod)
+      results[mod] = 'loaded'
+    } catch (e: any) {
+      // Expected: Cannot find module error when not in Bun runtime
+      results[mod] = e.message.includes('Cannot find module')
+        ? 'external (not found)'
+        : 'error'
+    }
+  }
+
+  // All modules should be external (not found when not in Bun)
+  const allExternal = Object.values(results).every(
+    (r) => r === 'external (not found)' || r === 'loaded'
+  )
+  return allExternal
+    ? 'All Bun modules are external'
+    : 'Some modules were not properly externalized'
+}

test/e2e/app-dir/bun-externals/app/server-action/page.tsx

@@ -0,0 +1,23 @@
+'use client'
+
+import { useState } from 'react'
+import { testBunExternals } from './actions'
+
+export default function ServerActionPage() {
+  const [result, setResult] = useState('')
+
+  async function handleClick() {
+    const res = await testBunExternals()
+    setResult(res)
+  }
+
+  return (
+    <div>
+      <h1>Server Action Test</h1>
+      <button id="test-action" onClick={handleClick}>
+        Test Bun Externals in Server Action
+      </button>
+      {result && <div id="action-result">{result}</div>}
+    </div>
+  )
+}

test/e2e/app-dir/bun-externals/bun-externals.test.ts

@@ -0,0 +1,74 @@
+import { nextTestSetup } from 'e2e-utils'
+
+describe('app-dir - bun externals', () => {
+  const { next, isNextDev, isTurbopack, skipped } = nextTestSetup({
+    files: __dirname,
+    skipDeployment: true,
+  })
+
+  if (skipped) {
+    return
+  }
+
+  it('should handle bun builtins as external modules', async () => {
+    const $ = await next.render$('/')
+
+    // When not running in Bun, these should throw "Cannot find module" errors
+    expect($('#bun-ffi').text()).toBe('external (not found)')
+    expect($('#bun-jsc').text()).toBe('external (not found)')
+    expect($('#bun-sqlite').text()).toBe('external (not found)')
+    expect($('#bun-test').text()).toBe('external (not found)')
+    expect($('#bun-wrap').text()).toBe('external (not found)')
+    expect($('#bun').text()).toBe('external (not found)')
+  })
+
+  it('should handle bun builtins in server actions', async () => {
+    const browser = await next.browser('/server-action')
+
+    await browser.elementByCss('#test-action').click()
+
+    await browser.waitForElementByCss('#action-result')
+    const result = await browser.elementByCss('#action-result').text()
+
+    expect(result).toContain('All Bun modules are external')
+  })
+
+  it('should handle bun builtins in route handlers', async () => {
+    const response = await next.fetch('/api/bun-externals')
+    const data = await response.json()
+
+    expect(data.bunFfi).toBe('external')
+    expect(data.bunJsc).toBe('external')
+    expect(data.bunSqlite).toBe('external')
+    expect(data.bunTest).toBe('external')
+    expect(data.bunWrap).toBe('external')
+    expect(data.bun).toBe('external')
+  })
+
+  it('should handle bun builtins in edge runtime', async () => {
+    const response = await next.fetch('/api/edge-bun-externals')
+    expect(await response.json()).toMatch(
+      /(Error: Cannot find module 'bun.*'|Error: Failed to load external module bun.*)/
+    )
+  })
+
+  if (!isTurbopack && !isNextDev) {
+    it('should not bundle bun builtins in server bundles', async () => {
+      await next.fetch('/')
+      const rscBundle = await next.readFile('.next/server/app/page.js')
+
+      expect(rscBundle).not.toContain('bun:ffi implementation')
+      expect(rscBundle).not.toContain('bun:jsc implementation')
+      expect(rscBundle).not.toContain('bun:sqlite implementation')
+      expect(rscBundle).not.toContain('bun:test implementation')
+      expect(rscBundle).not.toContain('bun:wrap implementation')
+
+      expect(rscBundle).toMatch(/require\(["']bun:ffi["']\)/)
+      expect(rscBundle).toMatch(/require\(["']bun:jsc["']\)/)
+      expect(rscBundle).toMatch(/require\(["']bun:sqlite["']\)/)
+      expect(rscBundle).toMatch(/require\(["']bun:test["']\)/)
+      expect(rscBundle).toMatch(/require\(["']bun:wrap["']\)/)
+      expect(rscBundle).toMatch(/require\(["']bun["']\)/)
+    })
+  }
+})