vinext 1.1.0 → 1.2.0

package/dist/shims/dynamic.js

@@ -1,19 +1,22 @@
+import { AppRouterTreeContext } from "./app-router-tree-context.js";
 import { DynamicPreloadChunks } from "./dynamic-preload-chunks.js";
 import React from "react";
 //#region src/shims/dynamic.ts
 /**
 * next/dynamic shim
 *
-* SSR-safe dynamic imports. On the server, uses React.lazy + Suspense so that
+* SSR-safe dynamic imports. On the server, uses React.lazy so that
 * renderToReadableStream suspends until the dynamically-imported component is
-* available. On the client, also uses React.lazy for code splitting.
+* available. On the client, also uses React.lazy for code splitting. As in
+* the Next.js App Router, a Suspense boundary is added only for `ssr: false`
+* or an explicit `loading` component. Other trees (Pages Router) keep it.
 *
 * Works in RSC, SSR, and client environments:
-* - RSC: Uses React.lazy + Suspense (available in React 19.x react-server).
+* - RSC: Uses React.lazy (available in React 19.x react-server).
 *   Falls back to async component pattern if a future React version
 *   strips lazy from react-server.
-* - SSR: React.lazy + Suspense (renderToReadableStream suspends)
-* - Client: React.lazy + Suspense (standard code splitting)
+* - SSR: React.lazy (renderToReadableStream suspends)
+* - Client: React.lazy (standard code splitting)
 *
 * Supports:
 * - dynamic(import('./Component'))
@@ -115,8 +118,55 @@ function getDynamicErrorBoundary() {
 }
 const isServer = typeof window === "undefined";
 /**
+* Whether this dynamic() renders in an App Router tree. RSC renders the App
+* Router only, and react-server has no context support. On the server, the
+* App Router SSR entry marks its tree; in the browser, App Router documents
+* set `window.next.appDir` before anything renders, which also covers
+* separate client roots (e.g. a modal rendered with createRoot). Everything
+* else (Pages Router pages, `pages/_document`, ad-hoc react-dom/server
+* renders) keeps the boundary, since Pages next/dynamic is react-loadable,
+* which never suspends.
+*/
+function useIsAppRouterTree() {
+	if (!isServer) return window.next?.appDir === true;
+	return AppRouterTreeContext ? React.use(AppRouterTreeContext) : true;
+}
+/**
+* The element tree around an SSR-enabled dynamic() component. The client
+* renders empty slots where the server renders the preload chunks, so both
+* sides render the same shape and useId values inside the dynamic component
+* match on hydration.
+*
+* Match Next.js App Router Loadable: the component only gets a Suspense
+* boundary when it has a `loading` component. Without one, the lazy component
+* suspends up to the nearest parent boundary, so the server shell waits for
+* the import instead of flushing an empty boundary and streaming the
+* component in after first paint. Other trees always get the boundary.
+*
+* React hoists the preload links out of place, but a hoisted <link> right
+* after a text node leaves a `<!-- -->` separator behind. Next.js avoids it by
+* hinting scripts with ReactDOM.preload(), which renders nothing. vinext
+* renders real modulepreload links (preloadModule() drops the nonce and
+* fetchPriority), so they go where text rarely precedes them: first inside the
+* boundary, or after the content when there is no boundary (a component whose
+* output ends in text still gets a separator after it). Stylesheets stay
+* before the boundary: a precedence stylesheet inside it makes React outline
+* the boundary even when its content is already resolved, and rendering them
+* ahead of the content keeps their nonce when the content links the same CSS.
+* A dynamic component with CSS right after text therefore still gets the
+* separator.
+*/
+function createDynamicBoundary(fallback, content, preloadModuleIds, hasBoundary) {
+	const preloadChunks = (assets) => isServer ? React.createElement(DynamicPreloadChunks, {
+		moduleIds: preloadModuleIds,
+		assets
+	}) : null;
+	if (!hasBoundary) return React.createElement(React.Fragment, null, preloadChunks("styles"), content, preloadChunks("scripts"));
+	return React.createElement(React.Fragment, null, preloadChunks("styles"), React.createElement(React.Suspense, { fallback }, preloadChunks("scripts"), content));
+}
+/**
 * Retained for the Pages Router render pipeline, which calls this before
-* rendering. Dynamic imports now use React.lazy + Suspense, so there is no
+* rendering. Dynamic imports now use React.lazy, so there is no
 * separate preload work to await.
 */
 function flushPreloads() {
@@ -170,6 +220,7 @@ function dynamic(dynamicInput, options) {
 		}
 		const LazyServer = createLazyComponent(loader);
 		const ServerDynamic = (props) => {
+			const isAppRouterTree = useIsAppRouterTree();
 			const fallback = LoadingComponent ? React.createElement(LoadingComponent, createDynamicLoadingProps()) : null;
 			const lazyElement = createElementWithProps(LazyServer, props);
 			let content = lazyElement;
@@ -181,7 +232,7 @@ function dynamic(dynamicInput, options) {
 					resetKey: 0
 				}, lazyElement);
 			}
-			return React.createElement(React.Fragment, null, React.createElement(DynamicPreloadChunks, { moduleIds: preloadModuleIds }), React.createElement(React.Suspense, { fallback }, content));
+			return createDynamicBoundary(fallback, content, preloadModuleIds, LoadingComponent != null || !isAppRouterTree);
 		};
 		ServerDynamic.displayName = "DynamicServer";
 		return ServerDynamic;
@@ -189,6 +240,7 @@ function dynamic(dynamicInput, options) {
 	const InitialLazyComponent = createLazyComponent(loader);
 	const ClientDynamic = (props) => {
 		const { LazyComponent, retry, retryKey } = useRetryableLazyComponent(loader, InitialLazyComponent);
+		const isAppRouterTree = useIsAppRouterTree();
 		const fallback = LoadingComponent ? React.createElement(LoadingComponent, createDynamicLoadingProps({ retry })) : null;
 		const lazyElement = createElementWithProps(LazyComponent, props);
 		let content = lazyElement;
@@ -200,7 +252,7 @@ function dynamic(dynamicInput, options) {
 				resetKey: retryKey
 			}, lazyElement);
 		}
-		return React.createElement(React.Suspense, { fallback }, content);
+		return createDynamicBoundary(fallback, content, preloadModuleIds, LoadingComponent != null || !isAppRouterTree);
 	};
 	ClientDynamic.displayName = "DynamicClient";
 	return ClientDynamic;

package/dist/shims/fetch-cache-state.d.ts

@@ -0,0 +1,66 @@
+//#region src/shims/fetch-cache-state.d.ts
+/**
+ * Request-scoped fetch cache state, kept apart from the fetch patching in
+ * fetch-cache.ts so modules that only read or update it, like next/cache,
+ * don't pull the patched fetch and its Node.js builtins into client graphs
+ * that import them.
+ */
+export type FetchDedupeEntry = {
+  key: string;
+  promise: Promise<Response>;
+  response: Response | null;
+};
+export type FetchCacheState = {
+  cacheableFetchUrls: Set<string>;
+  currentRequestTags: string[];
+  currentFetchSoftTags: string[];
+  currentFetchCacheMode: FetchCacheMode | null;
+  currentFetchRevalidate: number | null;
+  currentForceDynamicFetchDefault: boolean;
+  dynamicFetchUrls: Set<string>;
+  refreshStaleFetchesInForeground: boolean;
+  isFetchDedupeActive: boolean;
+  currentFetchDedupeEntries: Map<string, FetchDedupeEntry[]>;
+  nextFetchId: number;
+};
+export type FetchCacheMode = "auto" | "default-cache" | "default-no-store" | "force-cache" | "force-no-store" | "only-cache" | "only-no-store";
+export declare const fetchCacheAls: import("node:async_hooks").AsyncLocalStorage<FetchCacheState>;
+/**
+ * Process-wide state used only while the deprecated `withFetchCache()` is
+ * active, which marks it with `isFetchDedupeActive`.
+ */
+export declare const fallbackFetchCacheState: FetchCacheState;
+export declare function getFetchCacheState(): FetchCacheState;
+/**
+ * Reset the fallback state for a new request.  Used by `withFetchCache()`
+ * in single-threaded contexts where ALS.run() isn't used.
+ */
+export declare function resetFallbackFetchCacheState(isFetchDedupeActive: boolean): void;
+/**
+ * Append cache tags to the current request's collected tags.
+ *
+ * Mirrors Next.js's `propagateCacheLifeAndTagsToRevalidateStore`: tags declared
+ * inside a `"use cache"` function (via `cacheTag()`, persisted on the data cache
+ * entry) must also bubble up to the surrounding page / route-handler ISR entry
+ * so `revalidateTag()` / `revalidatePath()` can evict the rendered output, not
+ * just the inner data cache entry. Without this, a cached `"use cache"` result
+ * keeps being served from a stale page/route entry after its tag is revalidated
+ * (issue #1453). Tags are already encoded by the caller; deduped to match the
+ * tagged-fetch path. A no-op for empty input.
+ */
+export declare function addCollectedRequestTags(tags: readonly string[]): void;
+/**
+ * Read the path-derived soft tags for the current render.
+ *
+ * Used by the "use cache" runtime to pass soft tags to the cache handler
+ * so that `revalidatePath()` invalidates "use cache" entries during the
+ * affected route's next request, even when the entry carries no hard tags.
+ */
+export declare function getCurrentFetchSoftTags(): string[];
+/**
+ * Run `fn` with the request's fetch settings but its own record of the tags and
+ * URLs its fetches touch, so work done on the request's behalf after the fact
+ * (a background regeneration) leaves the request's response untouched.
+ */
+export declare function runWithDetachedFetchObservations<T>(fn: () => Promise<T>): Promise<T>;
+//#endregion

package/dist/shims/fetch-cache-state.js

@@ -0,0 +1,92 @@
+import { getOrCreateAls } from "./internal/als-registry.js";
+import { getRequestContext, isInsideUnifiedScope, runWithUnifiedStateMutation } from "./unified-request-context.js";
+//#region src/shims/fetch-cache-state.ts
+/**
+* Request-scoped fetch cache state, kept apart from the fetch patching in
+* fetch-cache.ts so modules that only read or update it, like next/cache,
+* don't pull the patched fetch and its Node.js builtins into client graphs
+* that import them.
+*/
+const _FALLBACK_KEY = Symbol.for("vinext.fetchCache.fallback");
+const fetchCacheAls = getOrCreateAls("vinext.fetchCache.als");
+function createFetchCacheState() {
+	return {
+		cacheableFetchUrls: /* @__PURE__ */ new Set(),
+		currentRequestTags: [],
+		currentFetchSoftTags: [],
+		currentFetchCacheMode: null,
+		currentFetchRevalidate: null,
+		currentForceDynamicFetchDefault: false,
+		dynamicFetchUrls: /* @__PURE__ */ new Set(),
+		refreshStaleFetchesInForeground: false,
+		isFetchDedupeActive: false,
+		currentFetchDedupeEntries: /* @__PURE__ */ new Map(),
+		nextFetchId: 1
+	};
+}
+/**
+* Process-wide state used only while the deprecated `withFetchCache()` is
+* active, which marks it with `isFetchDedupeActive`.
+*/
+const fallbackFetchCacheState = globalThis[_FALLBACK_KEY] ??= createFetchCacheState();
+function getFetchCacheState() {
+	if (isInsideUnifiedScope()) return getRequestContext();
+	const store = fetchCacheAls.getStore();
+	if (store) return store;
+	if (fallbackFetchCacheState.isFetchDedupeActive) return fallbackFetchCacheState;
+	return createFetchCacheState();
+}
+/**
+* Reset the fallback state for a new request.  Used by `withFetchCache()`
+* in single-threaded contexts where ALS.run() isn't used.
+*/
+function resetFallbackFetchCacheState(isFetchDedupeActive) {
+	Object.assign(fallbackFetchCacheState, createFetchCacheState(), { isFetchDedupeActive });
+}
+/**
+* Append cache tags to the current request's collected tags.
+*
+* Mirrors Next.js's `propagateCacheLifeAndTagsToRevalidateStore`: tags declared
+* inside a `"use cache"` function (via `cacheTag()`, persisted on the data cache
+* entry) must also bubble up to the surrounding page / route-handler ISR entry
+* so `revalidateTag()` / `revalidatePath()` can evict the rendered output, not
+* just the inner data cache entry. Without this, a cached `"use cache"` result
+* keeps being served from a stale page/route entry after its tag is revalidated
+* (issue #1453). Tags are already encoded by the caller; deduped to match the
+* tagged-fetch path. A no-op for empty input.
+*/
+function addCollectedRequestTags(tags) {
+	if (tags.length === 0) return;
+	const reqTags = getFetchCacheState().currentRequestTags;
+	for (const tag of tags) if (!reqTags.includes(tag)) reqTags.push(tag);
+}
+/**
+* Read the path-derived soft tags for the current render.
+*
+* Used by the "use cache" runtime to pass soft tags to the cache handler
+* so that `revalidatePath()` invalidates "use cache" entries during the
+* affected route's next request, even when the entry carries no hard tags.
+*/
+function getCurrentFetchSoftTags() {
+	return getFetchCacheState().currentFetchSoftTags;
+}
+/**
+* Run `fn` with the request's fetch settings but its own record of the tags and
+* URLs its fetches touch, so work done on the request's behalf after the fact
+* (a background regeneration) leaves the request's response untouched.
+*/
+function runWithDetachedFetchObservations(fn) {
+	if (isInsideUnifiedScope()) return runWithUnifiedStateMutation((uCtx) => {
+		uCtx.cacheableFetchUrls = /* @__PURE__ */ new Set();
+		uCtx.currentRequestTags = [];
+		uCtx.dynamicFetchUrls = /* @__PURE__ */ new Set();
+	}, fn);
+	return fetchCacheAls.run({
+		...getFetchCacheState(),
+		cacheableFetchUrls: /* @__PURE__ */ new Set(),
+		currentRequestTags: [],
+		dynamicFetchUrls: /* @__PURE__ */ new Set()
+	}, fn);
+}
+//#endregion
+export { addCollectedRequestTags, fallbackFetchCacheState, fetchCacheAls, getCurrentFetchSoftTags, getFetchCacheState, resetFallbackFetchCacheState, runWithDetachedFetchObservations };

package/dist/shims/fetch-cache.d.ts

@@ -1,33 +1,9 @@
+import { FetchCacheMode, FetchCacheState, addCollectedRequestTags, getCurrentFetchSoftTags, runWithDetachedFetchObservations } from "./fetch-cache-state.js";
 //#region src/shims/fetch-cache.d.ts
-/**
- * Extended fetch() with Next.js caching semantics.
- *
- * Patches `globalThis.fetch` during server rendering to support:
- *
- *   fetch(url, { next: { revalidate: 60, tags: ['posts'] } })
- *   fetch(url, { cache: 'force-cache' })
- *   fetch(url, { cache: 'no-store' })
- *
- * Cached responses are stored via the pluggable CacheHandler, so
- * revalidateTag() and revalidatePath() invalidate fetch-level caches.
- *
- * Usage (in server entry):
- *   import { withFetchCache, cleanupFetchCache } from './fetch-cache';
- *   const cleanup = withFetchCache();
- *   try { ... render ... } finally { cleanup(); }
- *
- * Or use the async helper:
- *   await runWithFetchCache(async () => { ... render ... });
- */
 type NextFetchOptions = {
   revalidate?: number | false;
   tags?: string[];
 };
-type FetchDedupeEntry = {
-  key: string;
-  promise: Promise<Response>;
-  response: Response | null;
-};
 declare global {
   interface RequestInit {
     next?: NextFetchOptions;
@@ -35,20 +11,6 @@ declare global {
 }
 /** @internal Reset dedup state — exposed for test isolation only. */
 export declare function _resetPendingRefetches(): void;
-export type FetchCacheState = {
-  cacheableFetchUrls: Set<string>;
-  currentRequestTags: string[];
-  currentFetchSoftTags: string[];
-  currentFetchCacheMode: FetchCacheMode | null;
-  currentFetchRevalidate: number | null;
-  currentForceDynamicFetchDefault: boolean;
-  dynamicFetchUrls: Set<string>;
-  refreshStaleFetchesInForeground: boolean;
-  isFetchDedupeActive: boolean;
-  currentFetchDedupeEntries: Map<string, FetchDedupeEntry[]>;
-  nextFetchId: number;
-};
-export type FetchCacheMode = "auto" | "default-cache" | "default-no-store" | "force-cache" | "force-no-store" | "only-cache" | "only-no-store";
 export declare function peekCacheableFetchObservations(): string[];
 export declare function peekDynamicFetchObservations(): string[];
 export declare function consumeDynamicFetchObservations(): string[];
@@ -58,19 +20,6 @@ export declare function consumeDynamicFetchObservations(): string[];
  * fetch tags used during rendering.
  */
 export declare function getCollectedFetchTags(): string[];
-/**
- * Append cache tags to the current request's collected tags.
- *
- * Mirrors Next.js's `propagateCacheLifeAndTagsToRevalidateStore`: tags declared
- * inside a `"use cache"` function (via `cacheTag()`, persisted on the data cache
- * entry) must also bubble up to the surrounding page / route-handler ISR entry
- * so `revalidateTag()` / `revalidatePath()` can evict the rendered output, not
- * just the inner data cache entry. Without this, a cached `"use cache"` result
- * keeps being served from a stale page/route entry after its tag is revalidated
- * (issue #1453). Tags are already encoded by the caller; deduped to match the
- * tagged-fetch path. A no-op for empty input.
- */
-export declare function addCollectedRequestTags(tags: readonly string[]): void;
 /**
  * Set path-derived implicit tags for fetch cache reads in the current render.
  *
@@ -79,14 +28,6 @@ export declare function addCollectedRequestTags(tags: readonly string[]): void;
  * affected route, without permanently coupling a shared fetch entry to one path.
  */
 export declare function setCurrentFetchSoftTags(tags: string[]): void;
-/**
- * Read the path-derived soft tags for the current render.
- *
- * Used by the "use cache" runtime to pass soft tags to the cache handler
- * so that `revalidatePath()` invalidates "use cache" entries during the
- * affected route's next request, even when the entry carries no hard tags.
- */
-export declare function getCurrentFetchSoftTags(): string[];
 export declare function setCurrentFetchCacheMode(mode: FetchCacheMode | null): void;
 export declare function setCurrentFetchRevalidate(revalidate: number | null): void;
 export declare function setCurrentForceDynamicFetchDefault(enabled: boolean): void;
@@ -103,12 +44,6 @@ export declare function setRefreshStaleFetchesInForeground(enabled: boolean): vo
  *   try { await render(); } finally { cleanup(); }
  */
 export declare function withFetchCache(): () => void;
-/**
- * Run `fn` with the request's fetch settings but its own record of the tags and
- * URLs its fetches touch, so work done on the request's behalf after the fact
- * (a background regeneration) leaves the request's response untouched.
- */
-export declare function runWithDetachedFetchObservations<T>(fn: () => Promise<T>): Promise<T>;
 /**
  * Run an async function with patched fetch caching enabled.
  * Uses `AsyncLocalStorage.run()` for proper per-request isolation
@@ -143,4 +78,5 @@ export declare function ensureFetchPatch(): void;
  * Useful for internal code that should bypass caching.
  */
 export declare function getOriginalFetch(): typeof globalThis.fetch;
-//#endregion
+//#endregion
+export { type FetchCacheMode, type FetchCacheState, addCollectedRequestTags, getCurrentFetchSoftTags, runWithDetachedFetchObservations };