offline navigations: register pass-through worker (3/11)

feedthejim · feedthejim · commit 8ac906e22703 · 2026-05-10T13:18:17.000-07:00
diff --git a/packages/next/src/build/index.ts b/packages/next/src/build/index.ts
@@ -237,6 +237,10 @@ import {
   createOfflineNavigationManifest,
   getOfflineNavigationManifestFilePath,
 } from './offline-navigation-manifest'
+import {
+  createOfflineNavigationServiceWorker,
+  getOfflineNavigationServiceWorkerFilePath,
+} from './offline-navigation-service-worker'
 
 type Fallback = null | boolean | string
 
@@ -4118,17 +4122,29 @@ export default async function build(
               distDir,
               getOfflineNavigationFallbackFilePath(buildId)
             )
+            const manifestPath = path.join(
+              distDir,
+              getOfflineNavigationManifestFilePath(buildId)
+            )
+            const serviceWorkerPath = path.join(
+              distDir,
+              getOfflineNavigationServiceWorkerFilePath()
+            )
+            const manifest = createOfflineNavigationManifest({
+              assetPrefix: config.assetPrefix,
+              basePath: config.basePath,
+              buildId,
+              output: config.output,
+              trailingSlash: config.trailingSlash,
+            })
+
             await mkdir(path.dirname(fallbackPath), { recursive: true })
             await writeFileUtf8(fallbackPath, fallbackDocument)
-
-            await writeManifest(
-              path.join(distDir, getOfflineNavigationManifestFilePath(buildId)),
-              createOfflineNavigationManifest({
-                assetPrefix: config.assetPrefix,
-                basePath: config.basePath,
-                buildId,
-                output: config.output,
-                trailingSlash: config.trailingSlash,
+            await writeManifest(manifestPath, manifest)
+            await writeFileUtf8(
+              serviceWorkerPath,
+              createOfflineNavigationServiceWorker({
+                manifestHref: manifest.manifest.href,
               })
             )
           })
diff --git a/packages/next/src/build/offline-navigation-manifest.ts b/packages/next/src/build/offline-navigation-manifest.ts
@@ -4,6 +4,7 @@ import type { NextConfigComplete } from '../server/config-shared'
 import { CLIENT_STATIC_FILES_PATH } from '../shared/lib/constants'
 import { encodeURIPath } from '../shared/lib/encode-uri-path'
 import { getOfflineNavigationFallbackFilePath } from './offline-navigation-fallback'
+import { getOfflineNavigationServiceWorkerFilePath } from './offline-navigation-service-worker'
 
 export const OFFLINE_NAVIGATION_MANIFEST = '_offline-navigation-manifest.json'
 
@@ -24,6 +25,10 @@ export interface OfflineNavigationManifest {
     path: string
     href: string
   }
+  serviceWorker: {
+    path: string
+    href: string
+  }
 }
 
 export function getOfflineNavigationManifestFilePath(buildId: string): string {
@@ -60,6 +65,7 @@ export function createOfflineNavigationManifest({
 }): OfflineNavigationManifest {
   const manifestPath = getOfflineNavigationManifestFilePath(buildId)
   const fallbackDocumentPath = getOfflineNavigationFallbackFilePath(buildId)
+  const serviceWorkerPath = getOfflineNavigationServiceWorkerFilePath()
 
   return {
     version: 1,
@@ -80,5 +86,9 @@ export function createOfflineNavigationManifest({
       path: fallbackDocumentPath,
       href: getStaticHref(basePath, fallbackDocumentPath),
     },
+    serviceWorker: {
+      path: serviceWorkerPath,
+      href: getStaticHref(basePath, serviceWorkerPath),
+    },
   }
 }
diff --git a/packages/next/src/build/offline-navigation-service-worker.ts b/packages/next/src/build/offline-navigation-service-worker.ts
@@ -0,0 +1,27 @@
+import path from 'node:path'
+
+import { CLIENT_STATIC_FILES_PATH } from '../shared/lib/constants'
+import { OFFLINE_NAVIGATION_SERVICE_WORKER } from '../shared/lib/offline-navigation'
+
+export function getOfflineNavigationServiceWorkerFilePath(): string {
+  return path.join(CLIENT_STATIC_FILES_PATH, OFFLINE_NAVIGATION_SERVICE_WORKER)
+}
+
+// Generate an app-local service worker for offline navigations. This slice is
+// pass-through: it only installs and claims clients so later slices can add
+// cache population and fallback document handling.
+export function createOfflineNavigationServiceWorker({
+  manifestHref,
+}: {
+  manifestHref: string
+}): string {
+  const metadata = JSON.stringify({
+    manifestHref,
+    source: 'offline-navigation-service-worker',
+  })
+
+  return `self.__NEXT_OFFLINE_NAVIGATION_SW=${metadata};
+self.addEventListener('install',(event)=>{event.waitUntil(self.skipWaiting())});
+self.addEventListener('activate',(event)=>{event.waitUntil(self.clients.claim())});
+`
+}
diff --git a/packages/next/src/client/app-index.tsx b/packages/next/src/client/app-index.tsx
@@ -376,6 +376,16 @@ export async function hydrate(
     setNavigationBuildId(getDeploymentId()!)
   }
 
+  if (process.env.__NEXT_OFFLINE_NAVIGATIONS) {
+    if (!process.env.__NEXT_DEV_SERVER) {
+      const { registerOfflineNavigationServiceWorker } =
+        require('./offline-navigation-service-worker') as typeof import('./offline-navigation-service-worker')
+      registerOfflineNavigationServiceWorker()
+    }
+  } else {
+    // Keep the service worker module out of disabled client bundles.
+  }
+
   const initialTimestamp = Date.now()
   const actionQueue: AppRouterActionQueue = createMutableActionQueue(
     createInitialRouterState({
diff --git a/packages/next/src/client/offline-navigation-service-worker.ts b/packages/next/src/client/offline-navigation-service-worker.ts
@@ -0,0 +1,35 @@
+import { getDeploymentIdQuery } from '../shared/lib/deployment-id'
+import { OFFLINE_NAVIGATION_SERVICE_WORKER } from '../shared/lib/offline-navigation'
+
+function getBasePath(): string {
+  return (process.env.__NEXT_ROUTER_BASEPATH as string) || ''
+}
+
+function getServiceWorkerHref(): string {
+  return `${getBasePath()}/_next/static/${OFFLINE_NAVIGATION_SERVICE_WORKER}${getDeploymentIdQuery()}`
+}
+
+function getServiceWorkerScope(): string {
+  const basePath = getBasePath()
+  return basePath ? `${basePath}/` : '/'
+}
+
+export function registerOfflineNavigationServiceWorker(): void {
+  if (
+    process.env.__NEXT_DEV_SERVER ||
+    typeof window === 'undefined' ||
+    !window.isSecureContext ||
+    !('serviceWorker' in navigator)
+  ) {
+    return
+  }
+
+  // Registration is best-effort: a failed service worker install should not
+  // affect the current online page load.
+  navigator.serviceWorker
+    .register(getServiceWorkerHref(), {
+      scope: getServiceWorkerScope(),
+      updateViaCache: 'none',
+    })
+    .catch(() => {})
+}
diff --git a/packages/next/src/server/lib/router-server.ts b/packages/next/src/server/lib/router-server.ts
@@ -13,6 +13,7 @@ import loadConfig, { type ConfiguredExperimentalFeature } from '../config'
 import { serveStatic } from '../serve-static'
 import setupDebug from 'next/dist/compiled/debug'
 import * as Log from '../../build/output/log'
+import { OFFLINE_NAVIGATION_SERVICE_WORKER } from '../../shared/lib/offline-navigation'
 import { DecodeError } from '../../shared/lib/utils'
 import { findPagesDir } from '../../lib/find-pages-dir'
 import { setupFsCheck } from './router-utils/filesystem'
@@ -524,6 +525,17 @@ export async function initialize(opts: {
         }
 
         if (
+          matchedOutput.type === 'nextStaticFolder' &&
+          matchedOutput.itemPath.endsWith(
+            `/${OFFLINE_NAVIGATION_SERVICE_WORKER}`
+          )
+        ) {
+          res.setHeader('Cache-Control', 'no-cache, must-revalidate')
+          res.setHeader(
+            'Service-Worker-Allowed',
+            config.basePath ? `${config.basePath}/` : '/'
+          )
+        } else if (
           !res.getHeader('cache-control') &&
           matchedOutput.type === 'nextStaticFolder'
         ) {
diff --git a/packages/next/src/shared/lib/offline-navigation.ts b/packages/next/src/shared/lib/offline-navigation.ts
@@ -0,0 +1,2 @@
+export const OFFLINE_NAVIGATION_SERVICE_WORKER =
+  '_offline-navigation-service-worker.js'
diff --git a/test/production/app-dir/offline-navigations/next.config.js b/test/production/app-dir/offline-navigations/next.config.js
@@ -3,7 +3,7 @@
  */
 const nextConfig = {
   cacheComponents: true,
-  assetPrefix: 'https://cdn.example.com/app-assets',
+  assetPrefix: '/app-assets',
   basePath: '/docs',
   experimental: {
     offlineNavigations: true,
diff --git a/test/production/app-dir/offline-navigations/offline-navigations.test.ts b/test/production/app-dir/offline-navigations/offline-navigations.test.ts
@@ -1,6 +1,7 @@
 import { existsSync } from 'fs'
 import { join } from 'path'
 import { nextTestSetup } from 'e2e-utils'
+import { retry } from 'next-test-utils'
 
 describe('offlineNavigations build artifacts', () => {
   const { next } = nextTestSetup({
@@ -23,6 +24,15 @@ describe('offlineNavigations build artifacts', () => {
         ),
         relativePath: `.next/static/${buildId}/_offline-navigation-fallback.html`,
       },
+      serviceWorker: {
+        absolutePath: join(
+          next.testDir,
+          '.next',
+          'static',
+          '_offline-navigation-service-worker.js'
+        ),
+        relativePath: `.next/static/_offline-navigation-service-worker.js`,
+      },
       manifest: {
         absolutePath: join(
           next.testDir,
@@ -40,23 +50,31 @@ describe('offlineNavigations build artifacts', () => {
     const buildResult = await next.build()
     expect(buildResult.exitCode).toBe(0)
 
-    const { buildId, fallbackDocument, manifest } =
+    const { buildId, fallbackDocument, manifest, serviceWorker } =
       await getOfflineNavigationArtifactPaths()
     const html = await next.readFile(fallbackDocument.relativePath)
     const manifestJson = JSON.parse(await next.readFile(manifest.relativePath))
+    const serviceWorkerScript = await next.readFile(serviceWorker.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('https://cdn.example.com/app-assets/_next/static/')
+    expect(html).toContain('/app-assets/_next/static/')
     expect(html).not.toContain('offline navigations page')
 
+    expect(serviceWorkerScript).toContain(
+      `"manifestHref":"/docs/_next/static/${buildId}/_offline-navigation-manifest.json"`
+    )
+    expect(serviceWorkerScript).toContain('skipWaiting')
+    expect(serviceWorkerScript).toContain('clients.claim')
+    expect(serviceWorkerScript).not.toContain('respondWith')
+
     expect(manifestJson).toEqual({
       version: 1,
       buildId,
       basePath: '/docs',
-      assetPrefix: 'https://cdn.example.com/app-assets',
+      assetPrefix: '/app-assets',
       trailingSlash: true,
       output: 'default',
       scope: '/docs/',
@@ -69,9 +87,72 @@ describe('offlineNavigations build artifacts', () => {
         path: `static/${buildId}/_offline-navigation-fallback.html`,
         href: `/docs/_next/static/${buildId}/_offline-navigation-fallback.html`,
       },
+      serviceWorker: {
+        path: `static/_offline-navigation-service-worker.js`,
+        href: `/docs/_next/static/_offline-navigation-service-worker.js`,
+      },
     })
   })
 
+  it('registers the pass-through service worker when enabled', async () => {
+    const buildResult = await next.build()
+    expect(buildResult.exitCode).toBe(0)
+
+    await next.start({ skipBuild: true })
+
+    try {
+      const swResponse = await next.fetch(
+        `/docs/_next/static/_offline-navigation-service-worker.js${next.getDeploymentIdQuery()}`
+      )
+      expect(swResponse.status).toBe(200)
+      expect(swResponse.headers.get('cache-control')).toBe(
+        'no-cache, must-revalidate'
+      )
+      expect(swResponse.headers.get('service-worker-allowed')).toBe('/docs/')
+
+      const browser = await next.browser('/docs')
+      await retry(async () => {
+        const registration = await browser.eval(async () => {
+          if (!('serviceWorker' in navigator)) {
+            return null
+          }
+
+          const registrations = await navigator.serviceWorker.getRegistrations()
+          const registration = registrations.find((registration) =>
+            registration.scope.endsWith('/docs/')
+          )
+
+          if (!registration) {
+            return null
+          }
+
+          return {
+            scope: registration.scope,
+            scriptURL: registration.active?.scriptURL ?? null,
+          }
+        })
+
+        expect(registration).toEqual({
+          scope: `${next.url}/docs/`,
+          scriptURL: `${next.url}/docs/_next/static/_offline-navigation-service-worker.js${next.getDeploymentIdQuery()}`,
+        })
+      })
+
+      await browser.eval(async () => {
+        if (!('serviceWorker' in navigator)) {
+          return
+        }
+
+        const registrations = await navigator.serviceWorker.getRegistrations()
+        await Promise.all(
+          registrations.map((registration) => registration.unregister())
+        )
+      })
+    } finally {
+      await next.stop()
+    }
+  })
+
   it('does not emit offline navigation artifacts when disabled', async () => {
     await next.patchFile('next.config.js', (content) =>
       content.replace('offlineNavigations: true', 'offlineNavigations: false')
@@ -80,9 +161,10 @@ describe('offlineNavigations build artifacts', () => {
     const buildResult = await next.build()
     expect(buildResult.exitCode).toBe(0)
 
-    const { fallbackDocument, manifest } =
+    const { fallbackDocument, manifest, serviceWorker } =
       await getOfflineNavigationArtifactPaths()
     expect(existsSync(fallbackDocument.absolutePath)).toBe(false)
     expect(existsSync(manifest.absolutePath)).toBe(false)
+    expect(existsSync(serviceWorker.absolutePath)).toBe(false)
   })
 })

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,2 @@`
	`1`	`+export const OFFLINE_NAVIGATION_SERVICE_WORKER =`
	`2`	`+ '_offline-navigation-service-worker.js'`