Dynamic Rendering

Copyexport function throwIfDisallowedDynamicInStaticRoute(
  workStore: WorkStore,
  prelude: PreludeState,
  dynamicValidation: DynamicValidationState,
  serverDynamic: DynamicTrackingState,
  isFallbackShell: boolean,
  allowEmptyStaticShell: boolean,
  isServerPartial: boolean
): void {
  const reasons = getDisallowedReasonsInStaticRoute(
    workStore,
    prelude,
    dynamicValidation,
    serverDynamic,
    isFallbackShell,
    allowEmptyStaticShell,
    isServerPartial
  )
  if (reasons.length > 0) {
    for (const reason of reasons) {
      logDisallowedDynamicError(workStore, reason)
    }
    throw new StaticGenBailoutError()
  }
}

Copyexport function unstable_noStore() {
  const callingExpression = 'unstable_noStore()'
  const store = workAsyncStorage.getStore()
  const workUnitStore = workUnitAsyncStorage.getStore()
  if (!store) {
    // This generally implies we are being called in Pages router. We should probably not support
    // unstable_noStore in contexts outside of `react-server` condition but since we historically
    // have not errored here previously, we maintain that behavior for now.
    return
  } else if (store.forceStatic) {
    return
  } else {
    store.isUnstableNoStore = true
    if (workUnitStore) {
      switch (workUnitStore.type) {
        case 'prerender':
        case 'prerender-client':
        case 'validation-client':
        case 'prerender-runtime':
          // unstable_noStore() is a noop in Dynamic I/O.
          return
        case 'prerender-legacy':
        case 'request':
        case 'cache':
        case 'private-cache':
        case 'unstable-cache':
        case 'build-time-generator':
          break
        default:
          workUnitStore satisfies never
      }
    }
    markCurrentScopeAsDynamic(store, workUnitStore, callingExpression)
  }
}

Copyexport function abortOnDynamicAccess(
  reason: DynamicAccessReason,
  error: Error
) {
  const store = dynamicAccessAsyncStorageInstance.getStore()
  if (store !== undefined) {
    // A cache may read both kinds of data before cancellation finishes. Only
    // fallback-only dependencies can become static when the params are known.
    if (store.reason !== 'runtime') {
      store.reason = reason
    }
    store.abortController.abort(error)
  }
}

Copy  expression: string,
  workUnitStore: WorkUnitStore | null
): Promise<T> {
  const promise = makeHangingPromiseWithError<T>(
    signal,
    new HangingPromiseRejectionError(route, expression)
  )
  if (workUnitStore === null) {
    return promise
  }
  return trackPromiseUsed(
    promise,
    trackURLDataAccessed.bind(null, workUnitStore, expression)
  )
}

Copyconst enum PrerenderDataKind {
  SessionData = 1,
  UrlData = 2,
  FallbackParams = 3,
}

Copyexport function useDynamicRouteParams(expression: string) {
  const workStore = workAsyncStorage.getStore()
  const workUnitStore = workUnitAsyncStorage.getStore()
  if (workStore && workUnitStore) {
    switch (workUnitStore.type) {
      case 'prerender-client': {
        const fallbackParams = workUnitStore.fallbackRouteParams
 
        if (fallbackParams && fallbackParams.size > 0) {
          // We are in a prerender with cacheComponents semantics. We are going to
          // hang here and never resolve. This will cause the currently
          // rendering component to effectively be a dynamic hole.
          React.use(
            makeClientHookHangingPromise(
              workUnitStore.renderSignal,
              new ClientHookDynamicError(workStore.route, expression)
            )
          )
        }
        break

Copyexport type OpaqueFallbackRouteParams = ReadonlyMap<string, string>
 
/**
 * Creates an opaque fallback route params object from the fallback route params.
 *
 * @param fallbackRouteParams the fallback route params
 * @returns the opaque fallback route params
 */
export function createOpaqueFallbackRouteParams(
  fallbackRouteParams: readonly FallbackRouteParam[]
): OpaqueFallbackRouteParams | null {
  // If there are no fallback route params, we can return early.
  if (fallbackRouteParams.length === 0) return null
 
  // As we're creating unique keys for each of the dynamic route params, we only
  // need to generate a unique ID once per request because each of the keys will
  // be also be unique.
  const uniqueID = Math.random().toString(16).slice(2)
 
  const keys = new Map<string, string>()
 
  // Generate a unique key for the fallback route param, if this key is found
  // in the static output, it represents a bug in cache components.
  for (const { paramName } of fallbackRouteParams) {
    keys.set(paramName, `%%drp:${paramName}:${uniqueID}%%`)
  }
 
  return keys
}

Copyexport function getStagedFallbackParams(route: {
  fallbackRouteParams: readonly FallbackRouteParam[] | undefined
  remainingPrerenderableParams?: readonly FallbackRouteParam[]
  throwOnEmptyStaticShell?: boolean
}): OpaqueFallbackRouteParams | null {
  const { fallbackRouteParams, remainingPrerenderableParams } = route
  if (!fallbackRouteParams?.length) {
    return null
  }
 
  if (route.throwOnEmptyStaticShell === undefined) {
    throw new InvariantError(
      'Expected throwOnEmptyStaticShell for a route with fallback params'
    )
  }
 
  // A required shell keeps all of its fallback params deferred.
  if (route.throwOnEmptyStaticShell || !remainingPrerenderableParams?.length) {
    return createOpaqueFallbackRouteParams(fallbackRouteParams)
  }
 
  return createOpaqueFallbackRouteParams(
    fallbackRouteParams.filter(
      (param) =>
        !remainingPrerenderableParams.some(
          (prerenderableParam) =>
            prerenderableParam.paramName === param.paramName
        )
    )
  )
}

Copyswitch (workUnitStore.type) {
  case 'prerender-runtime': {
    // TODO(runtime-ppr): does it make sense to delay this? normally it's always microtasky
    const { stagedRendering } = workUnitStore
    if (stagedRendering) {
      return stagedRendering.delayUntilStage(
        RENDER_STAGES_BY_DATA_KIND.sessionData,
        'draftMode',
        new DraftMode(workUnitStore.draftMode)
      )
    } else {
      return createOrGetCachedDraftMode(workUnitStore.draftMode, workStore)
    }
  }
  case 'request':
    return createOrGetCachedDraftMode(workUnitStore.draftMode, workStore)
 
  case 'cache':
  case 'private-cache':
  case 'unstable-cache':
    // Inside of `"use cache"` or `unstable_cache`, draft mode is available if
    // the outmost work unit store is a request store (or a runtime prerender),
    // and if draft mode is enabled.
    const draftModeProvider = getDraftModeProviderForCacheScope(
      workStore,
      workUnitStore
    )
 
    if (draftModeProvider) {
      return createOrGetCachedDraftMode(draftModeProvider, workStore)
    }
 
  // Otherwise, we fall through to providing an empty draft mode.
  // eslint-disable-next-line no-fallthrough
  case 'prerender':
  case 'prerender-legacy':
    // Return empty draft mode
    return createOrGetCachedDraftMode(null, workStore)
  case 'prerender-client':
  case 'validation-client': {
    const exportName = '`draftMode`'
    throw new InvariantError(
      `${exportName} must not be used within a Client Component. Next.js should be preventing ${exportName} from being included in Client Components statically, but did not in this case.`
    )
  }
  case 'build-time-generator':
    throw new Error(
      `Route ${workStore.route} used \`${callingExpression}()\` inside \`${workUnitStore.functionName}\`. This is not supported because \`${workUnitStore.functionName}\` runs at build time without an HTTP request. Read more: https://nextjs.org/docs/messages/next-dynamic-api-wrong-context`
    )
 
  default:
    return workUnitStore satisfies never
}

Copyfunction trackDynamicDraftMode(expression: string, constructorOpt: Function) {
  const workStore = workAsyncStorage.getStore()
  const workUnitStore = workUnitAsyncStorage.getStore()
 
  if (workStore) {
    // We have a store we want to track dynamic data access to ensure we
    // don't statically generate routes that manipulate draft mode.
    if (workUnitStore?.phase === 'after') {
      throw new Error(
        `Route ${workStore.route} used "${expression}" inside \`after()\`. The enabled status of \`draftMode()\` can be read inside \`after()\` but you cannot enable or disable \`draftMode()\`. See more info here: https://nextjs.org/docs/app/api-reference/functions/after`
      )
    }
 
    if (workStore.dynamicShouldError) {
      throw new StaticGenBailoutError(
        `Route ${workStore.route} with \`dynamic = "error"\` couldn't be rendered statically because it used \`${expression}\`. See more info here: https://nextjs.org/docs/app/building-your-application/rendering/static-and-dynamic#dynamic-rendering`
      )
    }
 
    if (workUnitStore) {
      switch (workUnitStore.type) {
        case 'cache':
        case 'private-cache': {
          const error = createDraftModeMutationInUseCacheError(
            workStore.route,
            expression
          )
          Error.captureStackTrace(error, constructorOpt)
          applyOwnerStack(error)
          workStore.invalidDynamicUsageError ??= error
          throw error
        }
        case 'unstable-cache':
          throw createDraftModeMutationInUnstableCacheError(
            workStore.route,
            expression
          )
 
        case 'prerender':
        case 'prerender-runtime': {
          const error = new Error(
            `Route ${workStore.route} used ${expression} without first calling \`await connection()\`. See more info here: https://nextjs.org/docs/messages/next-prerender-sync-headers`
          )
          return abortAndThrowOnSynchronousRequestDataAccess(
            workStore.route,
            expression,
            error,
            workUnitStore
          )
        }
        case 'prerender-client':
        case 'validation-client':
          const exportName = '`draftMode`'
          throw new InvariantError(
            `${exportName} must not be used within a Client Component. Next.js should be preventing ${exportName} from being included in Client Components statically, but did not in this case.`
          )
        case 'prerender-legacy':
          workUnitStore.revalidate = 0
 
          const err = new DynamicServerError(
            `Route ${workStore.route} couldn't be rendered statically because it used \`${expression}\`. See more info here: https://nextjs.org/docs/messages/dynamic-server-error`
          )
          workStore.dynamicUsageDescription = expression
          workStore.dynamicUsageStack = err.stack
 
          throw err
        case 'request':
          trackDynamicDataInDynamicRender(workUnitStore)
          break
        case 'build-time-generator':
          throw new Error(
            `Route ${workStore.route} used \`${expression}\` inside \`${workUnitStore.functionName}\`. This is not supported because \`${workUnitStore.functionName}\` runs at build time without an HTTP request. Read more: https://nextjs.org/docs/messages/next-dynamic-api-wrong-context`
          )
        default:
          workUnitStore satisfies never
      }
    }
  }

Copyexport class VaryParamsAccumulator implements AsyncIterable<VaryParamId> {
  private _resolve: ((result: IteratorResult<VaryParamId>) => void) | null =
    null
  private _done = false
  private _buffer: VaryParamId[] = []
  // The set of param names already yielded. Doubles as the dedupe guard so the
  // same name is never emitted twice.
  private _seen: Set<VaryParamId> = new Set()
 
  /**
   * Records that a param was accessed. Yields the name into the stream the
   * first time it's seen; subsequent accesses of the same name are no-ops.
   */
  add(id: VaryParamId): void {
    if (this._done || this._seen.has(id)) {
      return
    }
    this._seen.add(id)
    if (this._resolve !== null) {
      this._resolve({ value: id, done: false })
      this._resolve = null
    } else {
      this._buffer.push(id)
    }
  }
 
  /** Ends the iteration. Best-effort: if skipped (e.g. on a sync-I/O abort),
   * the consumer simply reads the params yielded so far. */
  close(): void {
    if (this._done) {
      return
    }
    this._done = true
    if (this._resolve !== null) {
      this._resolve({ value: undefined, done: true })
      this._resolve = null
    }
  }
 
  [Symbol.asyncIterator](): AsyncIterator<VaryParamId> {
    return {
      next: () => {
        if (this._buffer.length > 0) {
          return Promise.resolve({ value: this._buffer.shift()!, done: false })
        }
        if (this._done) {
          return Promise.resolve({ value: undefined, done: true })
        }
        return new Promise<IteratorResult<VaryParamId>>((resolve) => {
          this._resolve = resolve
        })
      },
    }
  }
}

Copyexport function createVaryingParams(
  accumulator: VaryParamsAccumulator,
  originalParamsObject: Params,
  optionalCatchAllParamName: string | null
): Params {
  if (optionalCatchAllParamName !== null) {
    // When there's an optional catch-all param with no value (e.g.,
    // [[...slug]] at /), the param doesn't exist as a property on the params
    // object. Use a Proxy to track all param access — both existing params
    // and the missing optional param — including enumeration patterns like
    // Object.keys(), spread, for...in, and `in` checks.
    return new Proxy(originalParamsObject, {
      get(target, prop, receiver) {
        if (typeof prop === 'string') {
          if (
            prop === optionalCatchAllParamName ||
            Object.prototype.hasOwnProperty.call(target, prop)
          ) {
            accumulateVaryParam(accumulator, prop)
          }
        }
        return Reflect.get(target, prop, receiver)
      },
      has(target, prop) {
        if (prop === optionalCatchAllParamName) {
          accumulateVaryParam(accumulator, optionalCatchAllParamName)
        }
        return Reflect.has(target, prop)
      },
      ownKeys(target) {
        // Enumerating the params object means the user's code may depend on
        // which params are present, so conservatively track the optional
        // param as accessed.
        accumulateVaryParam(accumulator, optionalCatchAllParamName)
        return Reflect.ownKeys(target)
      },
    })
  }
 
  // When there's no optional catch-all, all params exist as properties on the
  // object, so we can use defineProperty getters instead of a Proxy. This is
  // faster because the engine can optimize property access on regular objects
  // more aggressively than Proxy trap calls.
  const underlyingParamsWithVarying: Params = {}
  for (const paramName in originalParamsObject) {
    Object.defineProperty(underlyingParamsWithVarying, paramName, {
      get() {
        accumulateVaryParam(accumulator, paramName)
        return originalParamsObject[paramName]
      },
      enumerable: true,
    })
  }
  return underlyingParamsWithVarying
}
 
export function createVaryingSearchParams(
  accumulator: VaryParamsAccumulator,
  originalSearchParamsObject: SearchParams
): SearchParams {
  // Search params have no fixed schema, so any access — missing-key reads, `in`
  // checks, or enumeration — must register as varying. A Proxy is required
  // (rather than per-property getters) so that enumeration of an empty
  // searchParams object still triggers a vary. All accesses bucket into the
  // single search params id; the segment is keyed by the whole query string.
  // TODO: Split into per-param tracking if the cache key evolves.
  return new Proxy(originalSearchParamsObject, {
    get(target, prop, receiver) {
      if (typeof prop === 'string') {
        accumulateVaryParam(accumulator, SEARCH_PARAMS_VARY_ID)
      }
      return Reflect.get(target, prop, receiver)
    },
    has(target, prop) {
      if (typeof prop === 'string') {
        accumulateVaryParam(accumulator, SEARCH_PARAMS_VARY_ID)
      }
      return Reflect.has(target, prop)
    },
    ownKeys(target) {

Copyexport interface RenderResumeDataCache {
  /**
   * Discriminator. `false` means this cache is read-only and cannot be filled
   * with new entries. Used by `ResumeDataCache` consumers to narrow the union
   * via standard discriminated-union narrowing (e.g. `if
   * (resumeDataCache.mutable)`).
   */
  readonly mutable: false
 
  /**
   * A read-only Map store for values cached by the 'use cache' React hook.
   * The 'set' operation is omitted to enforce immutability.
   */
  readonly cache: Omit<UseCacheCacheStore, 'set'>
 
  /**
   * A read-only Map store for cached fetch responses.
   * The 'set' operation is omitted to enforce immutability.
   */
  readonly fetch: Omit<FetchCacheStore, 'set'>
 
  /**
   * A read-only Map store for encrypted bound args of inline server functions.
   * The 'set' operation is omitted to enforce immutability.
   */
  readonly encryptedBoundArgs: Omit<EncryptedBoundArgsCacheStore, 'set'>
 
  /**
   * A read-only Map store for decrypted bound args of inline server functions.
   * This is only intended for in-memory usage during pre-rendering, and must
   * not be persisted in the resume store. The 'set' operation is omitted to
   * enforce immutability.
   */
  readonly decryptedBoundArgs: Omit<DecryptedBoundArgsCacheStore, 'set'>
 
  /**
   * A read-only in-memory Map store for rendered `ImageResponse` array buffers.
   * This is only intended for in-memory usage during pre-rendering, and must
   * not be persisted in the resume store. The 'set' operation is omitted to
   * enforce immutability.
   */
  readonly imageResponses: Omit<ImageResponseCacheStore, 'set'>
}
 
/**
 * A mutable version of the resume data cache used during pre-rendering.
 * This cache allows both reading and writing of cached values.
 */
export interface PrerenderResumeDataCache {
  /**
   * Discriminator. `true` means this cache is mutable and can be filled with
   * new entries during this prerender. Used by `ResumeDataCache` consumers to
   * narrow the union via standard discriminated-union narrowing (e.g.
   * `if (resumeDataCache.mutable)`).
   */
  readonly mutable: true
 
  /**
   * A mutable Map store for values cached by the 'use cache' React hook.
   * Supports both 'get' and 'set' operations to build the cache during
   * pre-rendering.
   */
  readonly cache: UseCacheCacheStore
 
  /**
   * A mutable Map store for cached fetch responses.
   * Supports both 'get' and 'set' operations to build the cache during
   * pre-rendering.
   */
  readonly fetch: FetchCacheStore
 
  /**
   * A mutable Map store for encrypted bound args of inline server functions.
   * Supports both 'get' and 'set' operations to build the cache during
   * pre-rendering.
   */
  readonly encryptedBoundArgs: EncryptedBoundArgsCacheStore
 
  /**
   * A mutable Map store for decrypted bound args of inline server functions.

Copyconst hasDebugStaticShellQuery =
  process.env.__NEXT_EXPERIMENTAL_STATIC_SHELL_DEBUGGING === '1' &&
  typeof query.__nextppronly !== 'undefined' &&
  couldSupportPPR
 
// When enabled, this will allow the use of the `?__nextppronly` query
// to enable debugging of the fallback shell.
const hasDebugFallbackShellQuery =
  hasDebugStaticShellQuery && query.__nextppronly === 'fallback'
 
// Whether the testing API is exposed (dev mode or explicit flag)
const exposeTestingApi =
  nextConfig.cacheComponents === true &&
  (routeModule.isDev === true ||
    nextConfig.experimental.exposeTestingApiInProductionBuild === true)