Emit offline navigation fallback document

feedthejim · feedthejim · commit e8d5dedd5201 · 2026-05-07T20:57:36.000-07:00
diff --git a/packages/next/src/build/index.ts b/packages/next/src/build/index.ts
@@ -229,6 +229,10 @@ import {
 } from '../server/lib/router-utils/build-prefetch-segment-data-route'
 import { generateRoutesManifest } from './generate-routes-manifest'
 import { validateAppPaths } from './validate-app-paths'
+import {
+  createOfflineNavigationFallbackDocument,
+  getOfflineNavigationFallbackFilePath,
+} from './offline-navigation-fallback'
 
 type Fallback = null | boolean | string
 
@@ -4091,6 +4095,30 @@ export default async function build(
 
       // #endregion
 
+      if (config.experimental.offlineNavigations && appDir) {
+        await nextBuildSpan
+          .traceChild('write-offline-navigation-fallback')
+          .traceAsyncFn(async () => {
+            const fallbackDocument = createOfflineNavigationFallbackDocument({
+              assetPrefix: config.assetPrefix,
+              buildId,
+              buildManifest,
+              crossOrigin: config.crossOrigin,
+            })
+
+            if (fallbackDocument === null) {
+              return
+            }
+
+            const fallbackPath = path.join(
+              distDir,
+              getOfflineNavigationFallbackFilePath(buildId)
+            )
+            await mkdir(path.dirname(fallbackPath), { recursive: true })
+            await writeFileUtf8(fallbackPath, fallbackDocument)
+          })
+      }
+
       await writeImagesManifest(distDir, config)
       await writeManifest(path.join(distDir, EXPORT_MARKER), {
         version: 1,
diff --git a/packages/next/src/build/offline-navigation-fallback.ts b/packages/next/src/build/offline-navigation-fallback.ts
@@ -0,0 +1,84 @@
+import path from 'node:path'
+
+import type { BuildManifest } from '../server/get-page-files'
+import { encodeURIPath } from '../shared/lib/encode-uri-path'
+import {
+  htmlEscapeAttributeString,
+  htmlEscapeJsonString,
+} from '../shared/lib/htmlescape'
+import { CLIENT_STATIC_FILES_PATH } from '../shared/lib/constants'
+
+export const OFFLINE_NAVIGATION_FALLBACK_HTML =
+  '_offline-navigation-fallback.html'
+
+export function getOfflineNavigationFallbackFilePath(buildId: string): string {
+  return path.join(
+    CLIENT_STATIC_FILES_PATH,
+    buildId,
+    OFFLINE_NAVIGATION_FALLBACK_HTML
+  )
+}
+
+function getAssetHref(assetPrefix: string, file: string): string {
+  return `${assetPrefix}/_next/${encodeURIPath(file)}`
+}
+
+function getScriptAttributes(
+  crossOrigin: '' | 'anonymous' | 'use-credentials' | undefined
+): string {
+  if (!crossOrigin) {
+    return ''
+  }
+
+  return ` crossOrigin="${htmlEscapeAttributeString(crossOrigin)}"`
+}
+
+export function createOfflineNavigationFallbackDocument({
+  assetPrefix,
+  buildId,
+  buildManifest,
+  crossOrigin,
+}: {
+  assetPrefix: string
+  buildId: string
+  buildManifest: BuildManifest
+  crossOrigin: '' | 'anonymous' | 'use-credentials' | undefined
+}): string | null {
+  const rootMainFiles = buildManifest.rootMainFiles.filter((file) =>
+    file.endsWith('.js')
+  )
+
+  if (rootMainFiles.length === 0) {
+    return null
+  }
+
+  const polyfillScripts = buildManifest.polyfillFiles
+    .filter((file) => file.endsWith('.js') && !file.endsWith('.module.js'))
+    .map((file) => {
+      return `<script src="${htmlEscapeAttributeString(
+        getAssetHref(assetPrefix, file)
+      )}" noModule${getScriptAttributes(crossOrigin)}></script>`
+    })
+    .join('')
+
+  const bootstrapScripts = rootMainFiles
+    .map((file) => {
+      return `<script src="${htmlEscapeAttributeString(
+        getAssetHref(assetPrefix, file)
+      )}" async${getScriptAttributes(crossOrigin)}></script>`
+    })
+    .join('')
+
+  const metadata = {
+    buildId,
+    source: 'offline-navigation-fallback',
+  }
+
+  return `<!DOCTYPE html><html data-next-offline-navigation-fallback="" data-build-id="${htmlEscapeAttributeString(
+    buildId
+  )}"><head><meta charSet="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><meta name="next-offline-navigation-fallback" content="1"><meta name="next-build-id" content="${htmlEscapeAttributeString(
+    buildId
+  )}"><script id="__NEXT_OFFLINE_NAVIGATION_FALLBACK" type="application/json">${htmlEscapeJsonString(
+    JSON.stringify(metadata)
+  )}</script></head><body><div id="__next"></div><script>self.__next_f=self.__next_f||[];self.__next_f.push([0])</script>${polyfillScripts}${bootstrapScripts}</body></html>`
+}
diff --git a/test/production/app-dir/offline-navigations/app/layout.tsx b/test/production/app-dir/offline-navigations/app/layout.tsx
@@ -0,0 +1,8 @@
+import { ReactNode } from 'react'
+export default function Root({ children }: { children: ReactNode }) {
+  return (
+    <html>
+      <body>{children}</body>
+    </html>
+  )
+}
diff --git a/test/production/app-dir/offline-navigations/app/page.tsx b/test/production/app-dir/offline-navigations/app/page.tsx
@@ -0,0 +1,3 @@
+export default function Page() {
+  return <p>offline navigations page</p>
+}
diff --git a/test/production/app-dir/offline-navigations/next.config.js b/test/production/app-dir/offline-navigations/next.config.js
@@ -0,0 +1,11 @@
+/**
+ * @type {import('next').NextConfig}
+ */
+const nextConfig = {
+  cacheComponents: true,
+  experimental: {
+    offlineNavigations: true,
+  },
+}
+
+module.exports = nextConfig
diff --git a/test/production/app-dir/offline-navigations/offline-navigations.test.ts b/test/production/app-dir/offline-navigations/offline-navigations.test.ts
@@ -0,0 +1,53 @@
+import { existsSync } from 'fs'
+import { join } from 'path'
+import { nextTestSetup } from 'e2e-utils'
+
+describe('offlineNavigations fallback document', () => {
+  const { next } = nextTestSetup({
+    files: __dirname,
+    skipStart: true,
+  })
+
+  async function getFallbackDocumentPath() {
+    const buildId = (await next.readFile('.next/BUILD_ID')).trim()
+
+    return {
+      buildId,
+      absolutePath: join(
+        next.testDir,
+        '.next',
+        'static',
+        buildId,
+        '_offline-navigation-fallback.html'
+      ),
+      relativePath: `.next/static/${buildId}/_offline-navigation-fallback.html`,
+    }
+  }
+
+  it('emits a request-invariant fallback document when enabled', async () => {
+    const buildResult = await next.build()
+    expect(buildResult.exitCode).toBe(0)
+
+    const { buildId, relativePath } = await getFallbackDocumentPath()
+    const html = await next.readFile(relativePath)
+
+    expect(html).toContain('data-next-offline-navigation-fallback')
+    expect(html).toContain('id="__NEXT_OFFLINE_NAVIGATION_FALLBACK"')
+    expect(html).toContain(`"buildId":"${buildId}"`)
+    expect(html).toContain('self.__next_f')
+    expect(html).toContain('/_next/static/')
+    expect(html).not.toContain('offline navigations page')
+  })
+
+  it('does not emit a fallback document when disabled', async () => {
+    await next.patchFile('next.config.js', (content) =>
+      content.replace('offlineNavigations: true', 'offlineNavigations: false')
+    )
+
+    const buildResult = await next.build()
+    expect(buildResult.exitCode).toBe(0)
+
+    const { absolutePath } = await getFallbackDocumentPath()
+    expect(existsSync(absolutePath)).toBe(false)
+  })
+})

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+export default function Page() {`
	`2`	`+ return <p>offline navigations page</p>`
	`3`	`+}`