Gate alternate bundler behind canary only

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,7 @@ 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, isStableBuild } from '../shared/lib/canary-only'
 
 export { normalizeConfig } from './config-shared'
 export type { DomainLocale, NextConfig } from './config-shared'
@@ -244,20 +245,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 +1369,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.'
+    )
+  }
+}