Keep server code out of browser chunks (#76660)

Reduces the main chunk's size for a hello world app ~from 60.2 kB to
51.6 kB~ from 53.5 kB to 45.6 kB (after #76622 got merged).

In the past we were a bit sloppy with using modules from `src/server`
also in universally used modules (server & browser). This led to code
ending up in browser chunks that's only meant for the server, e.g. async
local storage modules.

We did have already quite a few conditional requires with `typeof
window` checks for those modules, but not everywhere. This is fixed in
this PR. And shared modules are also moved out of `src/server` into
either `src/shared/lib` or `src/client`.

A simple smoke test is added to ensure we don't regress here, at least
for a simple hello world app. A better verification might be some kind
of linter rule though.

In addition, we don't remove the `typeof window` SWC optimization for
Next.js modules anymore (which is still done for other `node_modules`,
see #62051), to ensure that guarded code becomes dead code and is
eliminated.

Ideally, SWC would take care of the DCE solely by using `typeof window`
checks, without needing to manually split modules and dynamically
requiring them, which is very tedious and we'd like to avoid. But this
is currently not the case.

Another option worth exploring is using the ESM modules from
`next/dist/esm` in hopes of yielding better DCE results.

Author: unstubbable

packages/next/src/build/normalize-catchall-routes.ts

@@ -1,4 +1,4 @@
-import { isInterceptionRouteAppPath } from '../server/lib/interception-routes'
+import { isInterceptionRouteAppPath } from '../shared/lib/router/utils/interception-routes'
 import { AppPathnameNormalizer } from '../server/normalizers/built/app/app-pathname-normalizer'
 
 /**

packages/next/src/build/swc/options.ts

@@ -513,7 +513,10 @@ export function getLoaderSWCOptions({
     options.cjsRequireOptimizer = undefined
     // Disable optimizer for node_modules in app browser layer, to avoid unnecessary replacement.
     // e.g. typeof window could result differently in js worker or browser.
-    if (options.jsc.transform.optimizer.globals?.typeofs) {
+    if (
+      options.jsc.transform.optimizer.globals?.typeofs &&
+      !filename.includes(nextDirname)
+    ) {
       delete options.jsc.transform.optimizer.globals.typeofs.window
     }
   }

packages/next/src/build/utils.ts

@@ -69,7 +69,7 @@ import { normalizeAppPath } from '../shared/lib/router/utils/app-paths'
 import { denormalizeAppPagePath } from '../shared/lib/page-path/denormalize-app-path'
 import { RouteKind } from '../server/route-kind'
 import type { PageExtensions } from './page-extensions-type'
-import { isInterceptionRouteAppPath } from '../server/lib/interception-routes'
+import { isInterceptionRouteAppPath } from '../shared/lib/router/utils/interception-routes'
 import { checkIsRoutePPREnabled } from '../server/lib/experimental/ppr'
 import type { FallbackMode } from '../lib/fallback'
 import type { OutgoingHttpHeaders } from 'http'

packages/next/src/client/components/client-page.tsx

@@ -51,10 +51,10 @@ export function ClientPageRoot({
     return <Component params={clientParams} searchParams={clientSearchParams} />
   } else {
     const { createRenderSearchParamsFromClient } =
-      require('../../server/request/search-params.browser') as typeof import('../../server/request/search-params.browser')
+      require('../request/search-params.browser') as typeof import('../request/search-params.browser')
     const clientSearchParams = createRenderSearchParamsFromClient(searchParams)
     const { createRenderParamsFromClient } =
-      require('../../server/request/params.browser') as typeof import('../../server/request/params.browser')
+      require('../request/params.browser') as typeof import('../request/params.browser')
     const clientParams = createRenderParamsFromClient(params)
 
     return <Component params={clientParams} searchParams={clientSearchParams} />

packages/next/src/client/components/client-segment.tsx

@@ -45,7 +45,7 @@ export function ClientSegmentRoot({
     return <Component {...slots} params={clientParams} />
   } else {
     const { createRenderParamsFromClient } =
-      require('../../server/request/params.browser') as typeof import('../../server/request/params.browser')
+      require('../request/params.browser') as typeof import('../request/params.browser')
     const clientParams = createRenderParamsFromClient(params)
     return <Component {...slots} params={clientParams} />
   }

packages/next/src/client/components/error-boundary.tsx

@@ -4,7 +4,13 @@ import React, { type JSX } from 'react'
 import { useUntrackedPathname } from './navigation-untracked'
 import { isNextRouterError } from './is-next-router-error'
 import { handleHardNavError } from './nav-failure-handler'
-import { workAsyncStorage } from '../../server/app-render/work-async-storage.external'
+
+const workAsyncStorage =
+  typeof window === 'undefined'
+    ? (
+        require('../../server/app-render/work-async-storage.external') as typeof import('../../server/app-render/work-async-storage.external')
+      ).workAsyncStorage
+    : undefined
 
 const styles = {
   error: {
@@ -54,10 +60,12 @@ interface ErrorBoundaryHandlerState {
 // function crashes so we can maintain our previous cache
 // instead of caching the error page
 function HandleISRError({ error }: { error: any }) {
-  const store = workAsyncStorage.getStore()
-  if (store?.isRevalidate || store?.isStaticGeneration) {
-    console.error(error)
-    throw error
+  if (workAsyncStorage) {
+    const store = workAsyncStorage.getStore()
+    if (store?.isRevalidate || store?.isStaticGeneration) {
+      console.error(error)
+      throw error
+    }
   }
 
   return null

packages/next/src/client/components/match-segments.ts

@@ -1,4 +1,3 @@
-import { getSegmentParam } from '../../server/app-render/get-segment-param'
 import type { Segment } from '../../server/app-render/types'
 
 export const matchSegment = (
@@ -19,17 +18,3 @@ export const matchSegment = (
   }
   return existingSegment[0] === segment[0] && existingSegment[1] === segment[1]
 }
-
-/*
- * This function is used to determine if an existing segment can be overridden by the incoming segment.
- */
-export const canSegmentBeOverridden = (
-  existingSegment: Segment,
-  segment: Segment
-): boolean => {
-  if (Array.isArray(existingSegment) || !Array.isArray(segment)) {
-    return false
-  }
-
-  return getSegmentParam(existingSegment)?.param === segment[0]
-}

packages/next/src/client/components/metadata/async-metadata.tsx

@@ -0,0 +1,42 @@
+'use client'
+
+import { Suspense, use } from 'react'
+import type { StreamingMetadataResolvedState } from './types'
+
+export const AsyncMetadata =
+  typeof window === 'undefined'
+    ? (
+        require('./server-inserted-metadata') as typeof import('./server-inserted-metadata')
+      ).ServerInsertMetadata
+    : (
+        require('./browser-resolved-metadata') as typeof import('./browser-resolved-metadata')
+      ).BrowserResolvedMetadata
+
+function MetadataOutlet({
+  promise,
+}: {
+  promise: Promise<StreamingMetadataResolvedState>
+}) {
+  const { error, digest } = use(promise)
+  if (error) {
+    if (digest) {
+      // The error will lose its original digest after passing from server layer to client layer；
+      // We recover the digest property here to override the React created one if original digest exists.
+      ;(error as any).digest = digest
+    }
+    throw error
+  }
+  return null
+}
+
+export function AsyncMetadataOutlet({
+  promise,
+}: {
+  promise: Promise<StreamingMetadataResolvedState>
+}) {
+  return (
+    <Suspense fallback={null}>
+      <MetadataOutlet promise={promise} />
+    </Suspense>
+  )
+}

packages/next/src/client/components/metadata/browser-resolved-metadata.tsx

@@ -0,0 +1,14 @@
+import { use } from 'react'
+import type { StreamingMetadataResolvedState } from './types'
+
+export function BrowserResolvedMetadata({
+  promise,
+}: {
+  promise: Promise<StreamingMetadataResolvedState>
+}) {
+  const { metadata, error } = use(promise)
+  // If there's metadata error on client, discard the browser metadata
+  // and let metadata outlet deal with the error. This will avoid the duplication metadata.
+  if (error) return null
+  return metadata
+}

packages/next/src/lib/metadata/metadata-boundary.tsx renamed to packages/next/src/client/components/metadata/metadata-boundary.tsx

@@ -4,7 +4,7 @@ import {
   METADATA_BOUNDARY_NAME,
   VIEWPORT_BOUNDARY_NAME,
   OUTLET_BOUNDARY_NAME,
-} from './metadata-constants'
+} from '../../../lib/metadata/metadata-constants'
 
 // We use a namespace object to allow us to recover the name of the function
 // at runtime even when production bundling/minification is used.

packages/next/src/client/components/metadata/server-inserted-metadata.ts

@@ -0,0 +1,29 @@
+import { use, useContext } from 'react'
+import {
+  type MetadataResolver,
+  ServerInsertedMetadataContext,
+} from '../../../shared/lib/server-inserted-metadata.shared-runtime'
+import type { StreamingMetadataResolvedState } from './types'
+
+// Receives a metadata resolver setter from the context, and will pass the metadata resolving promise to
+// the context where we gonna use it to resolve the metadata, and render as string to append in <body>.
+const useServerInsertedMetadata = (metadataResolver: MetadataResolver) => {
+  const setMetadataResolver = useContext(ServerInsertedMetadataContext)
+
+  if (setMetadataResolver) {
+    setMetadataResolver(metadataResolver)
+  }
+}
+
+export function ServerInsertMetadata({
+  promise,
+}: {
+  promise: Promise<StreamingMetadataResolvedState>
+}) {
+  // Apply use() to the metadata promise to suspend the rendering in SSR.
+  const { metadata } = use(promise)
+  // Insert metadata into the HTML stream through the `useServerInsertedMetadata`
+  useServerInsertedMetadata(() => metadata)
+
+  return null
+}

packages/next/src/client/components/metadata/types.ts

@@ -0,0 +1,5 @@
+export type StreamingMetadataResolvedState = {
+  metadata: React.ReactNode
+  error: unknown | null
+  digest: string | undefined
+}

packages/next/src/client/components/navigation.ts

@@ -15,7 +15,13 @@ import {
 import { getSegmentValue } from './router-reducer/reducers/get-segment-value'
 import { PAGE_SEGMENT_KEY, DEFAULT_SEGMENT_KEY } from '../../shared/lib/segment'
 import { ReadonlyURLSearchParams } from './navigation.react-server'
-import { useDynamicRouteParams } from '../../server/app-render/dynamic-rendering'
+
+const useDynamicRouteParams =
+  typeof window === 'undefined'
+    ? (
+        require('../../server/app-render/dynamic-rendering') as typeof import('../../server/app-render/dynamic-rendering')
+      ).useDynamicRouteParams
+    : undefined
 
 /**
  * A [Client Component](https://nextjs.org/docs/app/building-your-application/rendering/client-components) hook
@@ -84,7 +90,7 @@ export function useSearchParams(): ReadonlyURLSearchParams {
  */
 // Client components API
 export function usePathname(): string {
-  useDynamicRouteParams('usePathname()')
+  useDynamicRouteParams?.('usePathname()')
 
   // In the case where this is `null`, the compat types added in `next-env.d.ts`
   // will add a new overload that changes the return type to include `null`.
@@ -144,7 +150,7 @@ export function useRouter(): AppRouterInstance {
  */
 // Client components API
 export function useParams<T extends Params = Params>(): T {
-  useDynamicRouteParams('useParams()')
+  useDynamicRouteParams?.('useParams()')
 
   return useContext(PathParamsContext) as T
 }
@@ -215,7 +221,7 @@ function getSelectedLayoutSegmentPath(
 export function useSelectedLayoutSegments(
   parallelRouteKey: string = 'children'
 ): string[] {
-  useDynamicRouteParams('useSelectedLayoutSegments()')
+  useDynamicRouteParams?.('useSelectedLayoutSegments()')
 
   const context = useContext(LayoutRouterContext)
   // @ts-expect-error This only happens in `pages`. Type is overwritten in navigation.d.ts
@@ -246,7 +252,7 @@ export function useSelectedLayoutSegments(
 export function useSelectedLayoutSegment(
   parallelRouteKey: string = 'children'
 ): string | null {
-  useDynamicRouteParams('useSelectedLayoutSegment()')
+  useDynamicRouteParams?.('useSelectedLayoutSegment()')
 
   const selectedLayoutSegments = useSelectedLayoutSegments(parallelRouteKey)
 

packages/next/src/client/components/redirect.ts

@@ -1,4 +1,3 @@
-import { actionAsyncStorage } from '../../server/app-render/action-async-storage.external'
 import { RedirectStatusCode } from './redirect-status-code'
 import {
   RedirectType,
@@ -7,6 +6,13 @@ import {
   REDIRECT_ERROR_CODE,
 } from './redirect-error'
 
+const actionAsyncStorage =
+  typeof window === 'undefined'
+    ? (
+        require('../../server/app-render/action-async-storage.external') as typeof import('../../server/app-render/action-async-storage.external')
+      ).actionAsyncStorage
+    : undefined
+
 export function getRedirectError(
   url: string,
   type: RedirectType,
@@ -34,14 +40,11 @@ export function redirect(
   url: string,
   type?: RedirectType
 ): never {
-  const actionStore = actionAsyncStorage.getStore()
-  const redirectType =
-    type || (actionStore?.isAction ? RedirectType.push : RedirectType.replace)
-  throw getRedirectError(
-    url,
-    redirectType,
-    RedirectStatusCode.TemporaryRedirect
-  )
+  type ??= actionAsyncStorage?.getStore()?.isAction
+    ? RedirectType.push
+    : RedirectType.replace
+
+  throw getRedirectError(url, type, RedirectStatusCode.TemporaryRedirect)
 }
 
 /**

packages/next/src/client/components/router-reducer/compute-changed-path.ts

@@ -2,7 +2,7 @@ import type {
   FlightRouterState,
   Segment,
 } from '../../../server/app-render/types'
-import { INTERCEPTION_ROUTE_MARKERS } from '../../../server/lib/interception-routes'
+import { INTERCEPTION_ROUTE_MARKERS } from '../../../shared/lib/router/utils/interception-routes'
 import type { Params } from '../../../server/request/params'
 import {
   isGroupSegment,

packages/next/src/client/components/router-reducer/reducers/has-interception-route-in-current-tree.ts

@@ -1,5 +1,5 @@
 import type { FlightRouterState } from '../../../../server/app-render/types'
-import { isInterceptionRouteAppPath } from '../../../../server/lib/interception-routes'
+import { isInterceptionRouteAppPath } from '../../../../shared/lib/router/utils/interception-routes'
 
 export function hasInterceptionRouteInCurrentTree([
   segment,

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

@@ -46,7 +46,7 @@ import {
   encodeChildSegmentKey,
   encodeSegment,
   ROOT_SEGMENT_KEY,
-} from '../../../server/app-render/segment-value-encoding'
+} from '../../../shared/lib/segment-cache/segment-value-encoding'
 import type {
   FlightRouterState,
   NavigationFlightResponse,

packages/next/src/client/components/unstable-rethrow.browser.ts

@@ -0,0 +1,12 @@
+import { isBailoutToCSRError } from '../../shared/lib/lazy-dynamic/bailout-to-csr'
+import { isNextRouterError } from './is-next-router-error'
+
+export function unstable_rethrow(error: unknown): void {
+  if (isNextRouterError(error) || isBailoutToCSRError(error)) {
+    throw error
+  }
+
+  if (error instanceof Error && 'cause' in error) {
+    unstable_rethrow(error.cause)
+  }
+}

packages/next/src/client/components/unstable-rethrow.server.ts

@@ -0,0 +1,23 @@
+import { isHangingPromiseRejectionError } from '../../server/dynamic-rendering-utils'
+import { isPostpone } from '../../server/lib/router-utils/is-postpone'
+import { isBailoutToCSRError } from '../../shared/lib/lazy-dynamic/bailout-to-csr'
+import { isNextRouterError } from './is-next-router-error'
+import { isDynamicPostpone } from '../../server/app-render/dynamic-rendering'
+import { isDynamicServerError } from './hooks-server-context'
+
+export function unstable_rethrow(error: unknown): void {
+  if (
+    isNextRouterError(error) ||
+    isBailoutToCSRError(error) ||
+    isDynamicServerError(error) ||
+    isDynamicPostpone(error) ||
+    isPostpone(error) ||
+    isHangingPromiseRejectionError(error)
+  ) {
+    throw error
+  }
+
+  if (error instanceof Error && 'cause' in error) {
+    unstable_rethrow(error.cause)
+  }
+}

packages/next/src/client/components/unstable-rethrow.ts

@@ -1,28 +1,15 @@
-import { isDynamicUsageError } from '../../export/helpers/is-dynamic-usage-error'
-import { isHangingPromiseRejectionError } from '../../server/dynamic-rendering-utils'
-import { isPostpone } from '../../server/lib/router-utils/is-postpone'
-import { isBailoutToCSRError } from '../../shared/lib/lazy-dynamic/bailout-to-csr'
-import { isNextRouterError } from './is-next-router-error'
-
 /**
  * This function should be used to rethrow internal Next.js errors so that they can be handled by the framework.
  * When wrapping an API that uses errors to interrupt control flow, you should use this function before you do any error handling.
  * This function will rethrow the error if it is a Next.js error so it can be handled, otherwise it will do nothing.
  *
  * Read more: [Next.js Docs: `unstable_rethrow`](https://nextjs.org/docs/app/api-reference/functions/unstable_rethrow)
  */
-export function unstable_rethrow(error: unknown): void {
-  if (
-    isNextRouterError(error) ||
-    isBailoutToCSRError(error) ||
-    isDynamicUsageError(error) ||
-    isPostpone(error) ||
-    isHangingPromiseRejectionError(error)
-  ) {
-    throw error
-  }
-
-  if (error instanceof Error && 'cause' in error) {
-    unstable_rethrow(error.cause)
-  }
-}
+export const unstable_rethrow =
+  typeof window === 'undefined'
+    ? (
+        require('./unstable-rethrow.server') as typeof import('./unstable-rethrow.server')
+      ).unstable_rethrow
+    : (
+        require('./unstable-rethrow.browser') as typeof import('./unstable-rethrow.browser')
+      ).unstable_rethrow