Gate alternate bundler behind canary only

This restricts rspack to only be used with canary builds, and updates the plugin’s readme to note this, along with its experimental state.

Test Plan: Made a custom build with a `__NEXT_VERSION` of `15.2.0` and verified builds failed with the canary-only message.

packages/next-plugin-rspack/README.md

@@ -1,4 +1,7 @@
-# @next/plugin-rspack
+# @next/plugin-rspack (EXPERIMENTAL)
+
+> [!WARNING]
+> This package is currently experimental and actively developed and supported in Next.j's `canary` branch. To use this, you must be using a published canary build of Next.js.
 
 This plugin allows you to use [Rspack](https://rspack.dev) in place of webpack with Next.js.
 

packages/next/errors.json

@@ -649,5 +649,6 @@
   "648": "@rspack/plugin-react-refresh is not available. Please make sure `@next/plugin-rspack` is correctly installed.",
   "649": "Cache handlers not initialized",
   "650": "experimental.nodeMiddleware",
-  "651": "Unexpected module type %s"
+  "651": "Unexpected module type %s",
+  "652": "Rspack support is only available in Next.js canary."
 }

packages/next/src/server/config.ts

@@ -29,6 +29,8 @@ import { dset } from '../shared/lib/dset'
 import { normalizeZodErrors } from '../shared/lib/zod'
 import { HTML_LIMITED_BOT_UA_RE_STRING } from '../shared/lib/router/utils/is-bot'
 import { findDir } from '../lib/find-pages-dir'
+import { CanaryOnlyError } from '../shared/lib/canary-only-error'
+import { isStableBuild } from '../shared/lib/canary-only'
 
 export { normalizeConfig } from './config-shared'
 export type { DomainLocale, NextConfig } from './config-shared'
@@ -244,20 +246,18 @@ function assignDefaults(
     )
   }
 
-  if (
-    !process.env.__NEXT_VERSION?.includes('canary') &&
-    !process.env.__NEXT_TEST_MODE &&
-    !process.env.NEXT_PRIVATE_LOCAL_DEV
-  ) {
+  if (isStableBuild()) {
     // Prevents usage of certain experimental features outside of canary
     if (result.experimental?.ppr) {
-      throw new CanaryOnlyError('experimental.ppr')
+      throw new CanaryOnlyError({ feature: 'experimental.ppr' })
     } else if (result.experimental?.dynamicIO) {
-      throw new CanaryOnlyError('experimental.dynamicIO')
+      throw new CanaryOnlyError({ feature: 'experimental.dynamicIO' })
     } else if (result.experimental?.turbo?.unstablePersistentCaching) {
-      throw new CanaryOnlyError('experimental.turbo.unstablePersistentCaching')
+      throw new CanaryOnlyError({
+        feature: 'experimental.turbo.unstablePersistentCaching',
+      })
     } else if (result.experimental?.nodeMiddleware) {
-      throw new CanaryOnlyError('experimental.nodeMiddleware')
+      throw new CanaryOnlyError({ feature: 'experimental.nodeMiddleware' })
     }
   }
 
@@ -1370,14 +1370,3 @@ export function getConfiguredExperimentalFeatures(
   }
   return configuredExperimentalFeatures
 }
-
-class CanaryOnlyError extends Error {
-  constructor(feature: string) {
-    super(
-      `The experimental feature "${feature}" can only be enabled when using the latest canary version of Next.js.`
-    )
-    // This error is meant to interrupt the server start/build process
-    // but the stack trace isn't meaningful, as it points to internal code.
-    this.stack = undefined
-  }
-}

packages/next/src/shared/lib/canary-only.ts

@@ -0,0 +1,23 @@
+export function isStableBuild() {
+  return (
+    !process.env.__NEXT_VERSION?.includes('canary') &&
+    !process.env.__NEXT_TEST_MODE &&
+    !process.env.NEXT_PRIVATE_LOCAL_DEV
+  )
+}
+
+export class CanaryOnlyError extends Error {
+  constructor(arg: { feature: string } | string) {
+    if (typeof arg === 'object' && 'feature' in arg) {
+      super(
+        `The experimental feature "${arg.feature}" can only be enabled when using the latest canary version of Next.js.`
+      )
+    } else {
+      super(arg)
+    }
+
+    // This error is meant to interrupt the server start/build process
+    // but the stack trace isn't meaningful, as it points to internal code.
+    this.stack = undefined
+  }
+}

packages/next/src/shared/lib/get-rspack.ts

@@ -1,4 +1,7 @@
+import { CanaryOnlyError, isStableBuild } from './canary-only'
+
 export function getRspackCore() {
+  gateCanary()
   try {
     // eslint-disable-next-line import/no-extraneous-dependencies
     return require('@rspack/core')
@@ -14,6 +17,7 @@ export function getRspackCore() {
 }
 
 export function getRspackReactRefresh() {
+  gateCanary()
   try {
     // eslint-disable-next-line import/no-extraneous-dependencies
     return require('@rspack/plugin-react-refresh')
@@ -27,3 +31,11 @@ export function getRspackReactRefresh() {
     throw e
   }
 }
+
+function gateCanary() {
+  if (isStableBuild()) {
+    throw new CanaryOnlyError(
+      'Rspack support is only available in Next.js canary.'
+    )
+  }
+}