feat: use Rspack persistent cache by default

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

@@ -2361,7 +2361,7 @@ export default async function getBaseWebpackConfig(
     serverReferenceHashSalt: encryptionKey,
   })
 
-  const cache: any = {
+  const cache: webpack.Configuration['cache'] = {
     type: 'filesystem',
     // Disable memory cache in development in favor of our own MemoryWithGcCachePlugin.
     maxMemoryGenerations: dev ? 0 : Infinity, // Infinity is default value for production in webpack currently.
@@ -2407,6 +2407,30 @@ export default async function getBaseWebpackConfig(
 
   webpack5Config.cache = cache
 
+  if (isRspack) {
+    const buildDependencies: string[] = []
+    if (config.configFile) {
+      buildDependencies.push(config.configFile)
+    }
+    if (babelConfigFile) {
+      buildDependencies.push(babelConfigFile)
+    }
+    if (jsConfigPath) {
+      buildDependencies.push(jsConfigPath)
+    }
+
+    // @ts-ignore
+    webpack5Config.experiments.cache = {
+      type: 'persistent',
+      buildDependencies,
+      storage: {
+        type: 'filesystem',
+        directory: cache.cacheDirectory,
+      },
+      version: `${__dirname}|${process.env.__NEXT_VERSION}|${configVars}`,
+    }
+  }
+
   if (process.env.NEXT_WEBPACK_LOGGING) {
     const infra = process.env.NEXT_WEBPACK_LOGGING.includes('infrastructure')
     const profileClient =

packages/next/src/server/dev/hot-reloader-rspack.ts

@@ -0,0 +1,243 @@
+import path from 'path'
+import fs from 'fs/promises'
+import { createHash } from 'crypto'
+import HotReloaderWebpack from './hot-reloader-webpack'
+import { BUILT, EntryTypes, getEntries } from './on-demand-entry-handler'
+import type { __ApiPreviewProps } from '../api-utils'
+import type { RouteDefinition } from '../route-definitions/route-definition'
+import type { MultiCompiler } from 'webpack'
+import { COMPILER_NAMES } from '../../shared/lib/constants'
+
+/**
+ * Rspack Persistent Cache Strategy for Next.js Development
+ *
+ * Rspack's persistent caching differs from Webpack in how it manages module graphs.
+ * While Webpack incrementally updates modules, Rspack operates on complete module
+ * graph snapshots for cache restoration.
+ *
+ * Problem:
+ * - Next.js dev server starts with no page modules in the initial entry points
+ * - When Rspack restores from persistent cache, it finds no modules and purges
+ *   the entire module graph
+ * - Later page requests find no cached module information, preventing cache reuse
+ *
+ * Solution:
+ * - Track successfully built page entries after each compilation
+ * - Restore these entries on dev server restart to maintain module graph continuity
+ * - This ensures previously compiled pages can leverage persistent cache for faster builds
+ */
+export default class HotReloaderRspack extends HotReloaderWebpack {
+  private builtEntriesCachePath?: string
+
+  private isClientCacheEnabled = false
+  private isServerCacheEnabled = false
+  private isEdgeServerCacheEnabled = false
+
+  public async afterCompile(multiCompiler: MultiCompiler): Promise<void> {
+    // Always initialize the fallback error watcher for Rspack.
+    // Rspack may restore/retain the previous build's error state, so without this
+    // a page that previously failed to build might not be rebuilt on the next request.
+    await super.buildFallbackError()
+
+    const rspackStartSpan = this.hotReloaderSpan.traceChild(
+      'rspack-after-compile'
+    )
+    await rspackStartSpan.traceAsyncFn(async () => {
+      const hash = createHash('sha1')
+      multiCompiler.compilers.forEach((compiler) => {
+        const cache = compiler.options.cache
+        if (typeof cache === 'object' && 'version' in cache && cache.version) {
+          hash.update(cache.version)
+          if (compiler.name === COMPILER_NAMES.client) {
+            this.isClientCacheEnabled = true
+          } else if (compiler.name === COMPILER_NAMES.server) {
+            this.isServerCacheEnabled = true
+          } else if (compiler.name === COMPILER_NAMES.edgeServer) {
+            this.isEdgeServerCacheEnabled = true
+          }
+        } else {
+          hash.update('-')
+        }
+        return undefined
+      })
+      this.builtEntriesCachePath = path.join(
+        this.distDir,
+        'cache',
+        'rspack',
+        hash.digest('hex').substring(0, 16),
+        'built-entries.json'
+      )
+
+      const hasBuiltEntriesCache = await fs
+        .access(this.builtEntriesCachePath)
+        .then(
+          () => true,
+          () => false
+        )
+      if (hasBuiltEntriesCache) {
+        try {
+          const builtEntries: ReturnType<typeof getEntries> = JSON.parse(
+            (await fs.readFile(this.builtEntriesCachePath, 'utf-8')) || '{}'
+          )
+
+          await Promise.all(
+            Object.keys(builtEntries).map(async (entryKey) => {
+              const entryData = builtEntries[entryKey]
+
+              const isEntry = entryData.type === EntryTypes.ENTRY
+              const isChildEntry = entryData.type === EntryTypes.CHILD_ENTRY
+
+              // Check if the page was removed or disposed and remove it
+              if (isEntry) {
+                const pageExists =
+                  !entryData.dispose &&
+                  (await fs.access(entryData.absolutePagePath).then(
+                    () => true,
+                    () => false
+                  ))
+                if (!pageExists) {
+                  delete builtEntries[entryKey]
+                  return
+                } else if (
+                  !('hash' in builtEntries[entryKey]) ||
+                  builtEntries[entryKey].hash !==
+                    (await calculateFileHash(entryData.absolutePagePath))
+                ) {
+                  delete builtEntries[entryKey]
+                  return
+                }
+              }
+
+              // For child entries, if it has an entry file and it's gone, remove it
+              if (isChildEntry) {
+                if (entryData.absoluteEntryFilePath) {
+                  const pageExists =
+                    !entryData.dispose &&
+                    (await fs.access(entryData.absoluteEntryFilePath).then(
+                      () => true,
+                      () => false
+                    ))
+                  if (!pageExists) {
+                    delete builtEntries[entryKey]
+                    return
+                  } else {
+                    if (
+                      !('hash' in builtEntries[entryKey]) ||
+                      builtEntries[entryKey].hash !==
+                        (await calculateFileHash(
+                          entryData.absoluteEntryFilePath
+                        ))
+                    ) {
+                      delete builtEntries[entryKey]
+                      return
+                    }
+                  }
+                }
+              }
+            })
+          )
+          Object.assign(getEntries(multiCompiler.outputPath), builtEntries)
+        } catch (error) {
+          console.error('Rspack failed to read built entries cache: ', error)
+        }
+      }
+    })
+  }
+
+  public async ensurePage({
+    page,
+    clientOnly,
+    appPaths,
+    definition,
+    isApp,
+    url,
+  }: {
+    page: string
+    clientOnly: boolean
+    appPaths?: ReadonlyArray<string> | null
+    isApp?: boolean
+    definition?: RouteDefinition
+    url?: string
+  }): Promise<void> {
+    await super.ensurePage({
+      page,
+      clientOnly,
+      appPaths,
+      definition,
+      isApp,
+      url,
+    })
+    const entries = getEntries(this.multiCompiler!.outputPath)
+    const builtEntries: { [entryName: string]: any } = {}
+    await Promise.all(
+      Object.keys(entries).map(async (entryName) => {
+        const entry = entries[entryName]
+        if (entry.status !== BUILT) return
+        const result =
+          /^(client|server|edge-server)@(app|pages|root)@(.*)/g.exec(entryName)
+        const [, key /* pageType */, ,] = result! // this match should always happen
+        if (key === 'client' && !this.isClientCacheEnabled) return
+        if (key === 'server' && !this.isServerCacheEnabled) return
+        if (key === 'edge-server' && !this.isEdgeServerCacheEnabled) return
+
+        // TODO: Rspack does not store middleware entries in persistent cache, causing
+        // test/integration/middleware-src/test/index.test.ts to fail. This is a temporary
+        // workaround to skip middleware entry caching until Rspack properly supports it.
+        if (page === '/middleware') {
+          return
+        }
+
+        let hash: string | undefined
+        if (entry.type === EntryTypes.ENTRY) {
+          hash = await calculateFileHash(entry.absolutePagePath)
+        } else if (entry.absoluteEntryFilePath) {
+          hash = await calculateFileHash(entry.absoluteEntryFilePath)
+        }
+        if (!hash) {
+          return
+        }
+
+        builtEntries[entryName] = entry
+        builtEntries[entryName].hash = hash
+      })
+    )
+
+    const hasBuitEntriesCache = await fs
+      .access(this.builtEntriesCachePath!)
+      .then(
+        () => true,
+        () => false
+      )
+    try {
+      if (!hasBuitEntriesCache) {
+        await fs.mkdir(path.dirname(this.builtEntriesCachePath!), {
+          recursive: true,
+        })
+      }
+      await fs.writeFile(
+        this.builtEntriesCachePath!,
+        JSON.stringify(builtEntries, null, 2)
+      )
+    } catch (error) {
+      console.error('Rspack failed to write built entries cache: ', error)
+    }
+  }
+}
+
+async function calculateFileHash(
+  filePath: string,
+  algorithm: string = 'sha256'
+): Promise<string | undefined> {
+  if (
+    !(await fs.access(filePath).then(
+      () => true,
+      () => false
+    ))
+  ) {
+    return
+  }
+  const fileBuffer = await fs.readFile(filePath)
+  const hash = createHash(algorithm)
+  hash.update(fileBuffer)
+  return hash.digest('hex')
+}

packages/next/src/server/dev/hot-reloader-webpack.ts

@@ -226,18 +226,18 @@ function erroredPages(compilation: webpack.Compilation) {
 export default class HotReloaderWebpack implements NextJsHotReloaderInterface {
   private hasAppRouterEntrypoints: boolean
   private hasPagesRouterEntrypoints: boolean
-  private dir: string
-  private buildId: string
+  protected dir: string
+  protected buildId: string
   private encryptionKey: string
-  private middlewares: ((
+  protected middlewares: ((
     req: IncomingMessage,
     res: ServerResponse,
     next: () => void
   ) => Promise<void>)[]
-  private pagesDir?: string
-  private distDir: string
+  protected pagesDir?: string
+  protected distDir: string
   private webpackHotMiddleware?: WebpackHotMiddleware
-  private config: NextConfigComplete
+  protected config: NextConfigComplete
   private clientStats: webpack.Stats | null
   private clientError: Error | null = null
   private serverError: Error | null = null
@@ -246,13 +246,13 @@ export default class HotReloaderWebpack implements NextJsHotReloaderInterface {
   private serverChunkNames?: Set<string>
   private prevChunkNames?: Set<any>
   private onDemandEntries?: ReturnType<typeof onDemandEntryHandler>
-  private previewProps: __ApiPreviewProps
+  protected previewProps: __ApiPreviewProps
   private watcher: any
   private rewrites: CustomRoutes['rewrites']
   private fallbackWatcher: any
-  private hotReloaderSpan: Span
+  protected hotReloaderSpan: Span
   private pagesMapping: { [key: string]: string } = {}
-  private appDir?: string
+  protected appDir?: string
   private telemetry: Telemetry
   private resetFetch: () => void
   private lockfile: Lockfile | undefined
@@ -1243,6 +1243,8 @@ export default class HotReloaderWebpack implements NextJsHotReloaderInterface {
       this.activeWebpackConfigs
     ) as unknown as webpack.MultiCompiler
 
+    await this.afterCompile(this.multiCompiler)
+
     // Copy over the filesystem so that it is shared between all compilers.
     const inputFileSystem = this.multiCompiler.compilers[0].inputFileSystem
     for (const compiler of this.multiCompiler.compilers) {
@@ -1643,7 +1645,7 @@ export default class HotReloaderWebpack implements NextJsHotReloaderInterface {
       }),
     })
 
-    this.middlewares = [
+    this.middlewares.push(
       getOverlayMiddleware({
         rootDirectory: this.dir,
         isSrcDir: this.isSrcDir,
@@ -1694,9 +1696,8 @@ export default class HotReloaderWebpack implements NextJsHotReloaderInterface {
               getDevServerUrl: () => process.env.__NEXT_PRIVATE_ORIGIN,
             }),
           ]
-        : []),
-    ]
-
+        : [])
+    )
     setStackFrameResolver(async (request) => {
       return getOriginalStackFrames({
         isServer: request.isServer,
@@ -1711,6 +1712,8 @@ export default class HotReloaderWebpack implements NextJsHotReloaderInterface {
     })
   }
 
+  protected async afterCompile(_multiCompiler: webpack.MultiCompiler) {}
+
   public invalidate(
     { reloadAfterInvalidation }: { reloadAfterInvalidation: boolean } = {
       reloadAfterInvalidation: false,

packages/next/src/server/dev/on-demand-entry-handler.ts

@@ -8,7 +8,6 @@ import type {
 } from '../../shared/lib/app-router-types'
 import type { CompilerNameValues } from '../../shared/lib/constants'
 import type { RouteDefinition } from '../route-definitions/route-definition'
-import type HotReloaderWebpack from './hot-reloader-webpack'
 
 import createDebug from 'next/dist/compiled/debug'
 import { EventEmitter } from 'events'
@@ -39,6 +38,7 @@ import { PAGE_SEGMENT_KEY } from '../../shared/lib/segment'
 import {
   HMR_MESSAGE_SENT_TO_BROWSER,
   HMR_MESSAGE_SENT_TO_SERVER,
+  type NextJsHotReloaderInterface,
 } from './hot-reloader-types'
 import { isAppPageRouteDefinition } from '../route-definitions/app-page-route-definition'
 import { scheduleOnNextTick } from '../../lib/scheduler'
@@ -548,7 +548,7 @@ export function onDemandEntryHandler({
   rootDir,
   appDir,
 }: {
-  hotReloader: HotReloaderWebpack
+  hotReloader: NextJsHotReloaderInterface
   maxInactiveAge: number
   multiCompiler: webpack.MultiCompiler
   nextConfig: NextConfigComplete