[Segment Cache] Omit from bundle if flag disabled (#76622)

Alternative to #76597.

This works by importing all Segment Cache related code through a single
entry point (segment-cache.ts), and wrapping each export in a feature
flag check.

This fixes the size regression in v15.2 but long term I don't love this
approach. Since experimental flags are an essential part of our
workflow, we should establish a better pattern for dead code
elimination. Ideally it would be done at the bundler level, like how
React's build process works. In the React repo, you don't even need to
add any extra configuration per experiment — if the code is not
reachable, it gets stripped from the build automatically by Rollup. Or,
shorter term, we could stub out experimental modules at build time by
updating the build config, i.e. a more automated version of what I'm
doing manually for this particular flag.

Author: acdlite

.vscode/settings.json

@@ -61,7 +61,8 @@
     "packages/next/src/server/app-render/after-task-async-storage-instance.ts",
     "packages/next/src/server/app-render/clean-async-snapshot-instance.ts",
     "packages/next/src/server/app-render/work-async-storage-instance.ts",
-    "packages/next/src/server/app-render/work-unit-async-storage-instance.ts"
+    "packages/next/src/server/app-render/work-unit-async-storage-instance.ts",
+    "packages/next/src/client/components/segment-cache-impl/*"
   ],
   // Disable TypeScript surveys.
   "typescript.surveys.enabled": false,

packages/next/errors.json

@@ -651,5 +651,6 @@
   "650": "experimental.nodeMiddleware",
   "651": "Unexpected module type %s",
   "652": "Expected cached value for cache key %s not to be a %s kind, got \"FETCH\" instead.",
-  "653": "Expected cached value for cache key %s to be a \"FETCH\" kind, got %s instead."
+  "653": "Expected cached value for cache key %s to be a \"FETCH\" kind, got %s instead.",
+  "654": "Segment Cache experiment is not enabled. This is a bug in Next.js."
 }

packages/next/src/client/app-dir/form.tsx

@@ -16,10 +16,7 @@ import {
   hasUnsupportedSubmitterAttributes,
   type FormProps,
 } from '../form-shared'
-import {
-  mountLinkInstance,
-  unmountLinkInstance,
-} from '../components/segment-cache/links'
+import { mountLinkInstance, unmountLinkInstance } from '../components/links'
 
 export type { FormProps }
 

packages/next/src/client/app-dir/link.tsx

@@ -16,7 +16,7 @@ import {
   mountLinkInstance,
   onNavigationIntent,
   unmountLinkInstance,
-} from '../components/segment-cache/links'
+} from '../components/links'
 
 type Url = string | UrlObject
 type RequiredKeys<T> = {

packages/next/src/client/components/app-router.tsx

@@ -58,11 +58,11 @@ import type { FlightRouterState } from '../../server/app-render/types'
 import { useNavFailureHandler } from './nav-failure-handler'
 import { useServerActionDispatcher } from '../app-call-server'
 import type { AppRouterActionQueue } from '../../shared/lib/router/action-queue'
-import { prefetch as prefetchWithSegmentCache } from '../components/segment-cache/prefetch'
+import { prefetch as prefetchWithSegmentCache } from './segment-cache'
 import { getRedirectTypeFromError, getURLFromRedirectError } from './redirect'
 import { isRedirectError, RedirectType } from './redirect-error'
 import { prefetchReducer } from './router-reducer/reducers/prefetch-reducer'
-import { pingVisibleLinks } from './segment-cache/links'
+import { pingVisibleLinks } from './links'
 
 const globalMutable: {
   pendingMpaPath?: string

packages/next/src/client/components/segment-cache/links.ts renamed to packages/next/src/client/components/links.ts

@@ -1,17 +1,17 @@
-import type { FlightRouterState } from '../../../server/app-render/types'
-import type { AppRouterInstance } from '../../../shared/lib/app-router-context.shared-runtime'
-import { getCurrentAppRouterState } from '../../../shared/lib/router/action-queue'
-import { createPrefetchURL } from '../app-router'
-import { PrefetchKind } from '../router-reducer/router-reducer-types'
-import { getCurrentCacheVersion } from './cache'
-import { createCacheKey } from './cache-key'
+import type { FlightRouterState } from '../../server/app-render/types'
+import type { AppRouterInstance } from '../../shared/lib/app-router-context.shared-runtime'
+import { getCurrentAppRouterState } from '../../shared/lib/router/action-queue'
+import { createPrefetchURL } from './app-router'
+import { PrefetchKind } from './router-reducer/router-reducer-types'
+import { getCurrentCacheVersion } from './segment-cache'
+import { createCacheKey } from './segment-cache'
 import {
   type PrefetchTask,
   PrefetchPriority,
   schedulePrefetchTask as scheduleSegmentPrefetchTask,
   cancelPrefetchTask,
   bumpPrefetchTask,
-} from './scheduler'
+} from './segment-cache'
 
 type LinkElement = HTMLAnchorElement | SVGAElement | HTMLFormElement
 

packages/next/src/client/components/router-reducer/reducers/navigate-reducer.ts

@@ -32,7 +32,7 @@ import {
   navigate as navigateUsingSegmentCache,
   NavigationResultTag,
   type NavigationResult,
-} from '../../segment-cache/navigation'
+} from '../../segment-cache'
 
 export function handleExternalUrl(
   state: ReadonlyReducerState,
@@ -203,9 +203,6 @@ export function navigateReducer(
     // Temporary glue code between the router reducer and the new navigation
     // implementation. Eventually we'll rewrite the router reducer to a
     // state machine.
-    // TODO: Currently this always returns an async result, but in the future
-    // it will return a sync result if the navigation was prefetched. Hence
-    // a result type that's more complicated than you might expect.
     const result = navigateUsingSegmentCache(
       url,
       state.cache,

packages/next/src/client/components/router-reducer/reducers/prefetch-reducer.ts

@@ -8,7 +8,6 @@ import {
   getOrCreatePrefetchCacheEntry,
   prunePrefetchCache,
 } from '../prefetch-cache-utils'
-
 export const prefetchQueue = new PromiseQueue(5)
 
 export const prefetchReducer = process.env.__NEXT_CLIENT_SEGMENT_CACHE

packages/next/src/client/components/router-reducer/reducers/refresh-reducer.ts

@@ -16,7 +16,7 @@ import { createEmptyCacheNode } from '../../app-router'
 import { handleSegmentMismatch } from '../handle-segment-mismatch'
 import { hasInterceptionRouteInCurrentTree } from './has-interception-route-in-current-tree'
 import { refreshInactiveParallelSegments } from '../refetch-inactive-parallel-segments'
-import { revalidateEntireCache } from '../../segment-cache/cache'
+import { revalidateEntireCache } from '../../segment-cache'
 
 export function refreshReducer(
   state: ReadonlyReducerState,

packages/next/src/client/components/router-reducer/reducers/server-action-reducer.ts

@@ -56,7 +56,7 @@ import {
   extractInfoFromServerReferenceId,
   omitUnusedArgs,
 } from '../../../../shared/lib/server-reference-info'
-import { revalidateEntireCache } from '../../segment-cache/cache'
+import { revalidateEntireCache } from '../../segment-cache'
 
 type FetchServerActionResult = {
   redirectLocation: URL | undefined

packages/next/src/client/components/segment-cache/cache-key.ts renamed to packages/next/src/client/components/segment-cache-impl/cache-key.ts

@@ -52,7 +52,7 @@ import type {
 } from '../../../server/app-render/types'
 import { normalizeFlightData } from '../../flight-data-helpers'
 import { STATIC_STALETIME_MS } from '../router-reducer/prefetch-cache-utils'
-import { pingVisibleLinks } from './links'
+import { pingVisibleLinks } from '../links'
 
 // A note on async/await when working in the prefetch cache:
 //

packages/next/src/client/components/segment-cache/cache.ts renamed to packages/next/src/client/components/segment-cache-impl/cache.ts

@@ -24,13 +24,7 @@ import {
   type RouteTree,
 } from './cache'
 import { createCacheKey } from './cache-key'
-
-export const enum NavigationResultTag {
-  MPA,
-  Success,
-  NoOp,
-  Async,
-}
+import { NavigationResultTag } from '../segment-cache'
 
 type MPANavigationResult = {
   tag: NavigationResultTag.MPA

packages/next/src/client/components/segment-cache/lru.ts renamed to packages/next/src/client/components/segment-cache-impl/lru.ts

@@ -1,7 +1,8 @@
 import type { FlightRouterState } from '../../../server/app-render/types'
-import { createPrefetchURL } from '../../components/app-router'
+import { createPrefetchURL } from '../app-router'
 import { createCacheKey } from './cache-key'
-import { schedulePrefetchTask, PrefetchPriority } from './scheduler'
+import { schedulePrefetchTask } from './scheduler'
+import { PrefetchPriority } from '../segment-cache'
 
 /**
  * Entrypoint for prefetching a URL into the Segment Cache.

packages/next/src/client/components/segment-cache/navigation.ts renamed to packages/next/src/client/components/segment-cache-impl/navigation.ts

@@ -25,6 +25,7 @@ import {
   resetRevalidatingSegmentEntry,
 } from './cache'
 import type { RouteCacheKey } from './cache-key'
+import { PrefetchPriority } from '../segment-cache'
 
 const scheduleMicrotask =
   typeof queueMicrotask === 'function'
@@ -136,27 +137,6 @@ const enum PrefetchTaskExitStatus {
   Done,
 }
 
-/**
- * The priority of the prefetch task. Higher numbers are higher priority.
- */
-export const enum PrefetchPriority {
-  /**
-   * Assigned to any visible link that was hovered/touched at some point. This
-   * is not removed on mouse exit, because a link that was momentarily
-   * hovered is more likely to to be interacted with than one that was not.
-   */
-  Intent = 2,
-  /**
-   * The default priority for prefetch tasks.
-   */
-  Default = 1,
-  /**
-   * Assigned to tasks when they spawn non-blocking background work, like
-   * revalidating a partially cached entry to see if more data is available.
-   */
-  Background = 0,
-}
-
 /**
  * Prefetch tasks are processed in two phases: first the route tree is fetched,
  * then the segments. We use this to priortize tasks that have not yet fetched

packages/next/src/client/components/segment-cache/prefetch.ts renamed to packages/next/src/client/components/segment-cache-impl/prefetch.ts

@@ -0,0 +1,126 @@
+/**
+ * Entry point to the Segment Cache implementation.
+ *
+ * All code related to the Segment Cache lives `segment-cache-impl` directory.
+ * Callers access it through this indirection.
+ *
+ * This is to ensure the code is dead code eliminated from the bundle if the
+ * flag is disabled.
+ *
+ * TODO: This is super tedious. Since experimental flags are an essential part
+ * of our workflow, we should establish a better pattern for dead code
+ * elimination. Ideally it would be done at the bundler level, like how React's
+ * build process works. In the React repo, you don't even need to add any extra
+ * configuration per experiment — if the code is not reachable, it gets stripped
+ * from the build automatically by Rollup. Or, shorter term, we could stub out
+ * experimental modules at build time by updating the build config, i.e. a more
+ * automated version of what I'm doing manually in this file.
+ */
+
+export type { NavigationResult } from './segment-cache-impl/navigation'
+export type { PrefetchTask } from './segment-cache-impl/scheduler'
+
+const notEnabled: any = () => {
+  throw new Error(
+    'Segment Cache experiment is not enabled. This is a bug in Next.js.'
+  )
+}
+
+export const prefetch: typeof import('./segment-cache-impl/prefetch').prefetch =
+  process.env.__NEXT_CLIENT_SEGMENT_CACHE
+    ? function (...args) {
+        return require('./segment-cache-impl/prefetch').prefetch(...args)
+      }
+    : notEnabled
+
+export const navigate: typeof import('./segment-cache-impl/navigation').navigate =
+  process.env.__NEXT_CLIENT_SEGMENT_CACHE
+    ? function (...args) {
+        return require('./segment-cache-impl/navigation').navigate(...args)
+      }
+    : notEnabled
+
+export const revalidateEntireCache: typeof import('./segment-cache-impl/cache').revalidateEntireCache =
+  process.env.__NEXT_CLIENT_SEGMENT_CACHE
+    ? function (...args) {
+        return require('./segment-cache-impl/cache').revalidateEntireCache(
+          ...args
+        )
+      }
+    : notEnabled
+
+export const getCurrentCacheVersion: typeof import('./segment-cache-impl/cache').getCurrentCacheVersion =
+  process.env.__NEXT_CLIENT_SEGMENT_CACHE
+    ? function (...args) {
+        return require('./segment-cache-impl/cache').getCurrentCacheVersion(
+          ...args
+        )
+      }
+    : notEnabled
+
+export const schedulePrefetchTask: typeof import('./segment-cache-impl/scheduler').schedulePrefetchTask =
+  process.env.__NEXT_CLIENT_SEGMENT_CACHE
+    ? function (...args) {
+        return require('./segment-cache-impl/scheduler').schedulePrefetchTask(
+          ...args
+        )
+      }
+    : notEnabled
+
+export const cancelPrefetchTask: typeof import('./segment-cache-impl/scheduler').cancelPrefetchTask =
+  process.env.__NEXT_CLIENT_SEGMENT_CACHE
+    ? function (...args) {
+        return require('./segment-cache-impl/scheduler').cancelPrefetchTask(
+          ...args
+        )
+      }
+    : notEnabled
+
+export const bumpPrefetchTask: typeof import('./segment-cache-impl/scheduler').bumpPrefetchTask =
+  process.env.__NEXT_CLIENT_SEGMENT_CACHE
+    ? function (...args) {
+        return require('./segment-cache-impl/scheduler').bumpPrefetchTask(
+          ...args
+        )
+      }
+    : notEnabled
+
+export const createCacheKey: typeof import('./segment-cache-impl/cache-key').createCacheKey =
+  process.env.__NEXT_CLIENT_SEGMENT_CACHE
+    ? function (...args) {
+        return require('./segment-cache-impl/cache-key').createCacheKey(...args)
+      }
+    : notEnabled
+
+/**
+ * Below are public constants. They're small enough that we don't need to
+ * DCE them.
+ */
+
+export const enum NavigationResultTag {
+  MPA,
+  Success,
+  NoOp,
+  Async,
+}
+
+/**
+ * The priority of the prefetch task. Higher numbers are higher priority.
+ */
+export const enum PrefetchPriority {
+  /**
+   * Assigned to any visible link that was hovered/touched at some point. This
+   * is not removed on mouse exit, because a link that was momentarily
+   * hovered is more likely to to be interacted with than one that was not.
+   */
+  Intent = 2,
+  /**
+   * The default priority for prefetch tasks.
+   */
+  Default = 1,
+  /**
+   * Assigned to tasks when they spawn non-blocking background work, like
+   * revalidating a partially cached entry to see if more data is available.
+   */
+  Background = 0,
+}