offline navigations: emit fallback manifest data (2/13)

Author: feedthejim

packages/next/src/build/index.ts

@@ -233,6 +233,10 @@ import {
   createOfflineNavigationFallbackDocument,
   getOfflineNavigationFallbackFilePath,
 } from './offline-navigation-fallback'
+import {
+  createOfflineNavigationManifest,
+  getOfflineNavigationManifestFilePath,
+} from './offline-navigation-manifest'
 
 type Fallback = null | boolean | string
 
@@ -4097,7 +4101,7 @@ export default async function build(
 
       if (config.experimental.offlineNavigations && appDir) {
         await nextBuildSpan
-          .traceChild('write-offline-navigation-fallback')
+          .traceChild('write-offline-navigation-artifacts')
           .traceAsyncFn(async () => {
             const fallbackDocument = createOfflineNavigationFallbackDocument({
               assetPrefix: config.assetPrefix,
@@ -4116,6 +4120,17 @@ export default async function build(
             )
             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,
+              })
+            )
           })
       }
 

packages/next/src/build/offline-navigation-manifest.ts

@@ -0,0 +1,84 @@
+import path from 'node:path'
+
+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'
+
+export const OFFLINE_NAVIGATION_MANIFEST = '_offline-navigation-manifest.json'
+
+export interface OfflineNavigationManifest {
+  version: 1
+  buildId: string
+  basePath: string
+  assetPrefix: string
+  trailingSlash: boolean
+  output: NonNullable<NextConfigComplete['output']> | 'default'
+  scope: string
+  cacheNamespace: string
+  manifest: {
+    path: string
+    href: string
+  }
+  fallbackDocument: {
+    path: string
+    href: string
+  }
+}
+
+export function getOfflineNavigationManifestFilePath(buildId: string): string {
+  return path.join(
+    CLIENT_STATIC_FILES_PATH,
+    buildId,
+    OFFLINE_NAVIGATION_MANIFEST
+  )
+}
+
+function getStaticHref(basePath: string, filePath: string): string {
+  return `${basePath}/_next/${encodeURIPath(filePath)}`
+}
+
+function getScope(basePath: string): string {
+  return basePath ? `${basePath}/` : '/'
+}
+
+// Describe the build-scoped offline navigation artifacts with URLs that honor
+// the app basePath. Later slices use this manifest as the service worker's
+// source of truth for what bootstrap artifacts to cache.
+export function createOfflineNavigationManifest({
+  assetPrefix,
+  basePath,
+  buildId,
+  output,
+  trailingSlash,
+}: {
+  assetPrefix: string
+  basePath: string
+  buildId: string
+  output: NextConfigComplete['output']
+  trailingSlash: boolean
+}): OfflineNavigationManifest {
+  const manifestPath = getOfflineNavigationManifestFilePath(buildId)
+  const fallbackDocumentPath = getOfflineNavigationFallbackFilePath(buildId)
+
+  return {
+    version: 1,
+    buildId,
+    basePath,
+    assetPrefix,
+    trailingSlash,
+    output: output ?? 'default',
+    scope: getScope(basePath),
+    // Scope caches by build and basePath so a new deployment never reuses an
+    // older fallback document.
+    cacheNamespace: `next-offline-navigation-v1:${buildId}:${basePath || '/'}`,
+    manifest: {
+      path: manifestPath,
+      href: getStaticHref(basePath, manifestPath),
+    },
+    fallbackDocument: {
+      path: fallbackDocumentPath,
+      href: getStaticHref(basePath, fallbackDocumentPath),
+    },
+  }
+}

test/production/app-dir/offline-navigations/next.config.js

@@ -3,9 +3,12 @@
  */
 const nextConfig = {
   cacheComponents: true,
+  assetPrefix: 'https://cdn.example.com/app-assets',
+  basePath: '/docs',
   experimental: {
     offlineNavigations: true,
   },
+  trailingSlash: true,
 }
 
 module.exports = nextConfig

test/production/app-dir/offline-navigations/offline-navigations.test.ts

@@ -2,52 +2,87 @@ import { existsSync } from 'fs'
 import { join } from 'path'
 import { nextTestSetup } from 'e2e-utils'
 
-describe('offlineNavigations fallback document', () => {
+describe('offlineNavigations build artifacts', () => {
   const { next } = nextTestSetup({
     files: __dirname,
     skipStart: true,
   })
 
-  async function getFallbackDocumentPath() {
+  async function getOfflineNavigationArtifactPaths() {
     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`,
+      fallbackDocument: {
+        absolutePath: join(
+          next.testDir,
+          '.next',
+          'static',
+          buildId,
+          '_offline-navigation-fallback.html'
+        ),
+        relativePath: `.next/static/${buildId}/_offline-navigation-fallback.html`,
+      },
+      manifest: {
+        absolutePath: join(
+          next.testDir,
+          '.next',
+          'static',
+          buildId,
+          '_offline-navigation-manifest.json'
+        ),
+        relativePath: `.next/static/${buildId}/_offline-navigation-manifest.json`,
+      },
     }
   }
 
-  it('emits a request-invariant fallback document when enabled', async () => {
+  it('emits request-invariant offline navigation artifacts when enabled', async () => {
     const buildResult = await next.build()
     expect(buildResult.exitCode).toBe(0)
 
-    const { buildId, relativePath } = await getFallbackDocumentPath()
-    const html = await next.readFile(relativePath)
+    const { buildId, fallbackDocument, manifest } =
+      await getOfflineNavigationArtifactPaths()
+    const html = await next.readFile(fallbackDocument.relativePath)
+    const manifestJson = JSON.parse(await next.readFile(manifest.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).toContain('https://cdn.example.com/app-assets/_next/static/')
     expect(html).not.toContain('offline navigations page')
+
+    expect(manifestJson).toEqual({
+      version: 1,
+      buildId,
+      basePath: '/docs',
+      assetPrefix: 'https://cdn.example.com/app-assets',
+      trailingSlash: true,
+      output: 'default',
+      scope: '/docs/',
+      cacheNamespace: `next-offline-navigation-v1:${buildId}:/docs`,
+      manifest: {
+        path: `static/${buildId}/_offline-navigation-manifest.json`,
+        href: `/docs/_next/static/${buildId}/_offline-navigation-manifest.json`,
+      },
+      fallbackDocument: {
+        path: `static/${buildId}/_offline-navigation-fallback.html`,
+        href: `/docs/_next/static/${buildId}/_offline-navigation-fallback.html`,
+      },
+    })
   })
 
-  it('does not emit a fallback document when disabled', async () => {
+  it('does not emit offline navigation artifacts 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)
+    const { fallbackDocument, manifest } =
+      await getOfflineNavigationArtifactPaths()
+    expect(existsSync(fallbackDocument.absolutePath)).toBe(false)
+    expect(existsSync(manifest.absolutePath)).toBe(false)
   })
 })