Repository: vercel/next.js
Pull request: Automatically build and clear native build when running `pnpm build`

## What?

Adds a `maybe-build-native.mjs` script to `packages/next-swc/` that conditionally rebuilds native SWC bindings during `pnpm build`. The script is integrated into the turborepo pipeline as the `build` task for `@next/swc`.

## Why?

Developers often forget to run `pnpm swc-build-native` after pulling Rust changes, leading to confusing runtime errors. Conversely, rebuilding native binaries when nothing changed wastes significant time. This automates the decision so `pnpm build` always does the right thing.

## How?

The `maybe-build-native.mjs` script runs as `@next/swc`'s `build` task and:

1. **Skips in CI** — exits immediately when the `CI` env var is set, since CI uses prebuilt `@next/swc-*` npm packages
2. **Finds the last version bump** — uses `git log -G` to locate the commit that last changed `"version":` in `packages/next/package.json`
3. **Checks for Rust changes** — compares `*.rs` files against the working tree (committed + staged + unstaged) since that version bump commit
4. **Rebuilds if needed** — runs `build-native` and copies/formats the generated TypeScript definitions
5. **Clears stale binaries** — if no Rust changes are detected, removes any leftover `.node` files from `native/` so the prebuilt npm packages are used instead

Turborepo's `turbo.json` is configured with Rust-specific inputs (`crates/`, `Cargo.*`, `rust-toolchain`) and `CI` in `env` so CI and local builds get separate cache keys.

### Files changed
- `packages/next-swc/maybe-build-native.mjs` — new script with the conditional build logic
- `packages/next-swc/package.json` — added `"build": "node maybe-build-native.mjs"`
- `packages/next-swc/turbo.json` — added `build` task with Rust inputs, `CI` env, and `native/*.node` outputs

Changed files:
filename: AGENTS.md
patch: @@ -367,8 +367,7 @@ When running Next.js integration tests, you must rebuild if source files have ch
 
 - **First run after branch switch/bootstrap (or if unsure)?** → `pnpm build`
 - **Edited only core Next.js files (`packages/next/**`) after bootstrap?** → `pnpm --filter=next build`
-- **Edited Turbopack (Rust)?** → `pnpm swc-build-native`
-- **Edited both?** → `pnpm turbo build build-native`
+- **Edited Next.js code or Turbopack (Rust)?** → `pnpm build`
 
 ## Development Anti-Patterns
 

filename: packages/next-swc/maybe-build-native.mjs
patch: @@ -0,0 +1,110 @@
+import { execSync } from 'child_process'
+import { readdirSync, rmSync } from 'fs'
+import { dirname, join } from 'path'
+import { fileURLToPath } from 'url'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const PKG_DIR = __dirname
+const ROOT_DIR = join(__dirname, '../..')
+const NATIVE_DIR = join(PKG_DIR, 'native')
+
+function hasExistingNativeBinary() {
+  try {
+    const files = readdirSync(NATIVE_DIR)
+    return files.some((f) => f.endsWith('.node'))
+  } catch {
+    return false
+  }
+}
+
+function clearNativeBinaries() {
+  try {
+    const files = readdirSync(NATIVE_DIR)
+    for (const f of files) {
+      if (f.endsWith('.node')) {
+        rmSync(join(NATIVE_DIR, f))
+      }
+    }
+  } catch {
+    // directory doesn't exist, nothing to clear
+  }
+}
+
+function getVersionBumpCommit() {
+  try {
+    return (
+      execSync(
+        `git log -1 --format=%H -G '"version":' -- packages/next/package.json`,
+        { cwd: ROOT_DIR, encoding: 'utf8' }
+      ).trim() || null
+    )
+  } catch {
+    return null
+  }
+}
+
+function hasRustChanges(sinceCommit) {
+  try {
+    // Omit HEAD to compare against the working tree, which includes
+    // committed, staged, and unstaged changes.
+    const diff = execSync(
+      `git diff --name-only ${sinceCommit} -- ':(glob)**/*.rs' ':(glob)**/*.toml' ':(glob).cargo/**' Cargo.lock rust-toolchain`,
+      { cwd: ROOT_DIR, encoding: 'utf8' }
+    ).trim()
+    return diff.length > 0
+  } catch {
+    // If we can't determine whether changes occurred, assume they did
+    return true
+  }
+}
+
+function buildNative() {
+  console.log('Running swc-build-native...')
+  execSync('pnpm run swc-build-native', {
+    cwd: ROOT_DIR,
+    stdio: 'inherit',
+    env: {
+      ...process.env,
+      CARGO_TERM_COLOR: 'always',
+      TTY: '1',
+    },
+  })
+}
+
+function main() {
+  if (process.env.CI) {
+    console.log('Skipping swc-build-native in CI')
+    return
+  }
+
+  const versionBumpCommit = getVersionBumpCommit()
+
+  if (!versionBumpCommit) {
+    console.log(
+      'Could not determine version bump commit (shallow clone?), building native to be safe...'
+    )
+    buildNative()
+    return
+  }
+
+  if (hasRustChanges(versionBumpCommit)) {
+    console.log(
+      'Rust source files changed since last version bump, building native...'
+    )
+    buildNative()
+    return
+  }
+
+  // No Rust changes from the release version — clear any stale native build
+  // so the prebuilt @next/swc-* npm packages are used instead.
+  if (hasExistingNativeBinary()) {
+    console.log(
+      'No Rust changes since last version bump, clearing stale native binary...'
+    )
+    clearNativeBinaries()
+  }
+
+  console.log('Skipping swc-build-native (no Rust changes since version bump)')
+}
+
+main()

filename: packages/next-swc/package.json
patch: @@ -6,6 +6,7 @@
     "native/"
   ],
   "scripts": {
+    "build": "node maybe-build-native.mjs",
     "clean": "node ../../scripts/rm.mjs native",
     "build-native": "napi build --platform -p next-napi-bindings --cargo-cwd ../../ --cargo-name next_napi_bindings --features plugin,image-extended --js false native",
     "build-native-release": "napi build --platform -p next-napi-bindings --cargo-cwd ../../ --cargo-name next_napi_bindings --release --features plugin,image-extended,tracing/release_max_level_trace --js false native",

filename: packages/next-swc/turbo.json
patch: @@ -2,6 +2,23 @@
   "$schema": "https://turborepo.org/schema.json",
   "extends": ["//"],
   "tasks": {
+    "build": {
+      "inputs": [
+        "../../.cargo/**",
+        "../../crates/**",
+        "../../turbopack/crates/**",
+        "../../Cargo.toml",
+        "../../Cargo.lock",
+        "../../.github/workflows/build_and_deploy.yml",
+        "../../rust-toolchain"
+      ],
+      "env": ["CI"],
+      "outputs": [
+        "native/*.node",
+        "native/index.d.ts",
+        "../../packages/next/src/build/swc/generated-native.d.ts"
+      ]
+    },
     "build-native": {
       "inputs": [
         "../../.cargo/**",
@@ -13,7 +30,7 @@
         "../../rust-toolchain"
       ],
       "env": ["CI"],
-      "outputs": ["native/*.node"]
+      "outputs": ["native/*.node", "native/index.d.ts"]
     },
     "build-native-release": {
       "inputs": [
@@ -26,7 +43,7 @@
         "../../rust-toolchain"
       ],
       "env": ["CI"],
-      "outputs": ["native/*.node"]
+      "outputs": ["native/*.node", "native/index.d.ts"]
     },
     "build-native-release-with-assertions": {
       "inputs": [
@@ -39,7 +56,7 @@
         "../../rust-toolchain"
       ],
       "env": ["CI"],
-      "outputs": ["native/*.node"]
+      "outputs": ["native/*.node", "native/index.d.ts"]
     },
     "build-native-no-plugin": {
       "inputs": [
@@ -52,7 +69,7 @@
         "../../rust-toolchain"
       ],
       "env": ["CI"],
-      "outputs": ["native/*.node"]
+      "outputs": ["native/*.node", "native/index.d.ts"]
     },
     "build-native-no-plugin-release": {
       "inputs": [
@@ -65,7 +82,7 @@
         "../../rust-toolchain"
       ],
       "env": ["CI"],
-      "outputs": ["native/*.node"]
+      "outputs": ["native/*.node", "native/index.d.ts"]
     },
     "build-wasm": {
       "inputs": [
@@ -104,7 +121,7 @@
         "../../rust-toolchain"
       ],
       "env": ["CI"],
-      "outputs": ["native/*.node"]
+      "outputs": ["native/*.node", "native/index.d.ts"]
     },
     "rust-check": {
       "dependsOn": ["rust-check-fmt", "rust-check-clippy", "rust-check-napi"]

filename: scripts/build-native.ts
patch: @@ -4,7 +4,7 @@ import { promises as fs } from 'node:fs'
 import path from 'node:path'
 import url from 'node:url'
 import execa from 'execa'
-import { NEXT_DIR, logCommand, execFn } from './pack-util'
+import { NEXT_DIR, logCommand } from './pack-util'
 
 const nextSwcDir = path.join(NEXT_DIR, 'packages/next-swc')
 
@@ -25,10 +25,7 @@ export default async function buildNative(
     stdio: 'inherit',
   })
 
-  await execFn(
-    'Copy generated types to `next/src/build/swc/generated-native.d.ts`',
-    () => writeTypes()
-  )
+  await writeTypes()
 }
 
 // Check if this file is being run directly
@@ -56,17 +53,31 @@ async function writeTypes() {
   const generatedTypes = await fs.readFile(generatedTypesPath, 'utf8')
   let vendoredTypes = await fs.readFile(vendoredTypesPath, 'utf8')
 
+  const existingContent = vendoredTypes
   vendoredTypes = vendoredTypes.split(generatedTypesMarker)[0]
   vendoredTypes =
     vendoredTypes + generatedTypesMarker + generatedNotice + generatedTypes
 
-  await fs.writeFile(vendoredTypesPath, vendoredTypes)
-
-  const prettifyCommand = ['prettier', '--write', vendoredTypesPath]
+  const prettifyCommand = ['prettier', '--stdin-filepath', vendoredTypesPath]
   logCommand('Prettify generated types', prettifyCommand)
-  await execa(prettifyCommand[0], prettifyCommand.slice(1), {
-    cwd: NEXT_DIR,
-    stdio: 'inherit',
-    preferLocal: true,
-  })
+  const prettierResult = await execa(
+    prettifyCommand[0],
+    prettifyCommand.slice(1),
+    {
+      cwd: NEXT_DIR,
+      input: vendoredTypes,
+      preferLocal: true,
+    }
+  )
+  vendoredTypes = prettierResult.stdout
+  if (!vendoredTypes.endsWith('\n')) {
+    vendoredTypes += '\n'
+  }
+
+  if (vendoredTypes === existingContent) {
+    return
+  }
+
+  logCommand('Write generated types', `write file`)
+  await fs.writeFile(vendoredTypesPath, vendoredTypes)
 }