Unverified Commit 2ca99e1e authored by Andrew Clark's avatar Andrew Clark Committed by GitHub

Add experimental.appShells feature flag (#93997)

Plumbing for upcoming App Shell prefetching support: sets up the config
field, the zod entry, and the build-time `process.env.__NEXT_APP_SHELLS`
define. No behavior change in this PR — nothing reads the flag yet.
Subsequent PRs in this sequence wire the server- and client-side work
behind it.

Enabling `experimental.appShells` requires several adjacent flags to
also be enabled: `cacheComponents`, `experimental.prefetchInlining`,
`experimental.varyParams`, `experimental.optimisticRouting`, and
`experimental.cachedNavigations`. All of these are on track to become
defaults soon, so there's no value in supporting App Shells against
arbitrary subsets — the validation enforces that App Shells is tested in
the configuration it will ship with. Each requirement drops out as the
corresponding flag becomes a default.
<!-- NEXT_JS_LLM_PR -->
parent 5b6747ad
...@@ -1276,5 +1276,6 @@ ...@@ -1276,5 +1276,6 @@
"1275": "\\`experimental.cssChunking: false\\` is only supported with webpack. Please remove the option or run Next.js with webpack in %s.", "1275": "\\`experimental.cssChunking: false\\` is only supported with webpack. Please remove the option or run Next.js with webpack in %s.",
"1276": "Compilation failed but no issues were recorded", "1276": "Compilation failed but no issues were recorded",
"1277": "no route matched for path \"%s\"", "1277": "no route matched for path \"%s\"",
"1278": "compileRoute: either routeSpecifier or path is required" "1278": "compileRoute: either routeSpecifier or path is required",
"1279": "\\`experimental.appShells\\` requires the following to also be enabled: %s. Please update your %s accordingly."
} }
...@@ -380,6 +380,7 @@ export function getDefineEnv({ ...@@ -380,6 +380,7 @@ export function getDefineEnv({
config.experimental.gestureTransition ?? false, config.experimental.gestureTransition ?? false,
'process.env.__NEXT_OPTIMISTIC_ROUTING': 'process.env.__NEXT_OPTIMISTIC_ROUTING':
config.experimental.optimisticRouting ?? false, config.experimental.optimisticRouting ?? false,
'process.env.__NEXT_APP_SHELLS': config.experimental.appShells ?? false,
'process.env.__NEXT_VARY_PARAMS': config.experimental.varyParams ?? false, 'process.env.__NEXT_VARY_PARAMS': config.experimental.varyParams ?? false,
'process.env.__NEXT_EXPOSE_TESTING_API': 'process.env.__NEXT_EXPOSE_TESTING_API':
dev || config.experimental.exposeTestingApiInProductionBuild === true, dev || config.experimental.exposeTestingApiInProductionBuild === true,
......
...@@ -224,6 +224,7 @@ export const experimentalSchema = { ...@@ -224,6 +224,7 @@ export const experimentalSchema = {
dynamicOnHover: z.boolean().optional(), dynamicOnHover: z.boolean().optional(),
useOffline: z.boolean().optional(), useOffline: z.boolean().optional(),
optimisticRouting: z.boolean().optional(), optimisticRouting: z.boolean().optional(),
appShells: z.boolean().optional(),
varyParams: z.boolean().optional(), varyParams: z.boolean().optional(),
prefetchInlining: z prefetchInlining: z
.union([ .union([
......
...@@ -470,6 +470,14 @@ export interface ExperimentalConfig { ...@@ -470,6 +470,14 @@ export interface ExperimentalConfig {
dynamicOnHover?: boolean dynamicOnHover?: boolean
useOffline?: boolean useOffline?: boolean
optimisticRouting?: boolean optimisticRouting?: boolean
/**
* Enables App Shell prefetching: a route's reusable, param-free loading
* state is prefetched once per session and served instantly for any
* concrete navigation. Routes marked as fully static (no per-request
* server work) are unaffected; the App Shell phase only runs for
* runtime-prefetchable routes.
*/
appShells?: boolean
varyParams?: boolean varyParams?: boolean
prefetchInlining?: prefetchInlining?:
| boolean | boolean
...@@ -2117,6 +2125,7 @@ export interface NextConfigRuntime { ...@@ -2117,6 +2125,7 @@ export interface NextConfigRuntime {
| 'dynamicOnHover' | 'dynamicOnHover'
| 'useOffline' | 'useOffline'
| 'optimisticRouting' | 'optimisticRouting'
| 'appShells'
| 'inlineCss' | 'inlineCss'
| 'prefetchInlining' | 'prefetchInlining'
| 'authInterrupts' | 'authInterrupts'
...@@ -2184,6 +2193,7 @@ export function getNextConfigRuntime( ...@@ -2184,6 +2193,7 @@ export function getNextConfigRuntime(
dynamicOnHover: ex.dynamicOnHover, dynamicOnHover: ex.dynamicOnHover,
useOffline: ex.useOffline, useOffline: ex.useOffline,
optimisticRouting: ex.optimisticRouting, optimisticRouting: ex.optimisticRouting,
appShells: ex.appShells,
inlineCss: ex.inlineCss, inlineCss: ex.inlineCss,
prefetchInlining: ex.prefetchInlining, prefetchInlining: ex.prefetchInlining,
authInterrupts: ex.authInterrupts, authInterrupts: ex.authInterrupts,
......
...@@ -502,6 +502,35 @@ function assignDefaultsAndValidate( ...@@ -502,6 +502,35 @@ function assignDefaultsAndValidate(
) )
} }
if (result.experimental.appShells) {
// App Shells is tested in combination with the experimental flags it
// expects to ship alongside. All of these are on track to become
// defaults, so we don't support enabling App Shells against arbitrary
// subsets of them — the validation goes away once each becomes a
// default.
const missing: string[] = []
if (!result.cacheComponents) {
missing.push('`cacheComponents`')
}
if (!result.experimental.prefetchInlining) {
missing.push('`experimental.prefetchInlining`')
}
if (!result.experimental.varyParams) {
missing.push('`experimental.varyParams`')
}
if (!result.experimental.optimisticRouting) {
missing.push('`experimental.optimisticRouting`')
}
if (!result.experimental.cachedNavigations) {
missing.push('`experimental.cachedNavigations`')
}
if (missing.length > 0) {
throw new Error(
`\`experimental.appShells\` requires the following to also be enabled: ${missing.join(', ')}. Please update your ${configFileName} accordingly.`
)
}
}
if (result.experimental.ppr) { if (result.experimental.ppr) {
throw new HardDeprecatedConfigError( throw new HardDeprecatedConfigError(
`\`experimental.ppr\` has been merged into \`cacheComponents\`. The Partial Prerendering feature is still available, but is now enabled via \`cacheComponents\`. Please update your ${configFileName} accordingly.` `\`experimental.ppr\` has been merged into \`cacheComponents\`. The Partial Prerendering feature is still available, but is now enabled via \`cacheComponents\`. Please update your ${configFileName} accordingly.`
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment