Introduce standalone experimental.useCache flag (#75240)

vercel · Jan 23, 2025 · bf726d3 · bf726d3
1 parent 8b71caa
commit bf726d3
Show file tree

Hide file tree

Showing 37 changed files with 318 additions and 259 deletions.
diff --git a/crates/next-core/src/next_client/transforms.rs b/crates/next-core/src/next_client/transforms.rs
@@ -49,7 +49,7 @@ pub async fn get_next_client_transforms_rules(
         rules.push(get_debug_fn_name_rule(enable_mdx_rs));
     }
 
-    let dynamic_io_enabled = *next_config.enable_dynamic_io().await?;
+    let use_cache_enabled = *next_config.enable_use_cache().await?;
     let cache_kinds = next_config.cache_kinds().to_resolved().await?;
     let mut is_app_dir = false;
 
@@ -77,7 +77,7 @@ pub async fn get_next_client_transforms_rules(
                 ActionsTransform::Client,
                 encryption_key,
                 enable_mdx_rs,
-                dynamic_io_enabled,
+                use_cache_enabled,
                 cache_kinds,
             ));
         }

diff --git a/crates/next-core/src/next_config.rs b/crates/next-core/src/next_config.rs
@@ -666,6 +666,7 @@ pub struct ExperimentalConfig {
     react_compiler: Option<ReactCompilerOptionsOrBoolean>,
     #[serde(rename = "dynamicIO")]
     dynamic_io: Option<bool>,
+    use_cache: Option<bool>,
     // ---
     // UNSUPPORTED
     // ---
@@ -1408,6 +1409,18 @@ impl NextConfig {
         Vc::cell(self.experimental.dynamic_io.unwrap_or(false))
     }
 
+    #[turbo_tasks::function]
+    pub fn enable_use_cache(&self) -> Vc<bool> {
+        Vc::cell(
+            self.experimental
+                .use_cache
+                // "use cache" was originally implicitly enabled with the
+                // dynamicIO flag, so we transfer the value for dynamicIO to the
+                // explicit useCache flag to ensure backwards compatibility.
+                .unwrap_or(self.experimental.dynamic_io.unwrap_or(false)),
+        )
+    }
+
     #[turbo_tasks::function]
     pub fn cache_kinds(&self) -> Vc<CacheKinds> {
         Vc::cell(

diff --git a/crates/next-core/src/next_server/transforms.rs b/crates/next-core/src/next_server/transforms.rs
@@ -77,7 +77,7 @@ pub async fn get_next_server_transforms_rules(
         ));
     }
 
-    let dynamic_io_enabled = *next_config.enable_dynamic_io().await?;
+    let use_cache_enabled = *next_config.enable_use_cache().await?;
     let cache_kinds = next_config.cache_kinds().to_resolved().await?;
     let mut is_app_dir = false;
 
@@ -115,7 +115,7 @@ pub async fn get_next_server_transforms_rules(
                 ActionsTransform::Client,
                 encryption_key,
                 mdx_rs,
-                dynamic_io_enabled,
+                use_cache_enabled,
                 cache_kinds,
             ));
 
@@ -128,7 +128,7 @@ pub async fn get_next_server_transforms_rules(
                 ActionsTransform::Server,
                 encryption_key,
                 mdx_rs,
-                dynamic_io_enabled,
+                use_cache_enabled,
                 cache_kinds,
             ));
 
@@ -141,7 +141,7 @@ pub async fn get_next_server_transforms_rules(
                 ActionsTransform::Server,
                 encryption_key,
                 mdx_rs,
-                dynamic_io_enabled,
+                use_cache_enabled,
                 cache_kinds,
             ));
 

diff --git a/crates/next-core/src/next_shared/transforms/server_actions.rs b/crates/next-core/src/next_shared/transforms/server_actions.rs
@@ -21,14 +21,14 @@ pub fn get_server_actions_transform_rule(
     transform: ActionsTransform,
     encryption_key: ResolvedVc<RcStr>,
     enable_mdx_rs: bool,
-    dynamic_io_enabled: bool,
+    use_cache_enabled: bool,
     cache_kinds: ResolvedVc<CacheKinds>,
 ) -> ModuleRule {
     let transformer =
         EcmascriptInputTransform::Plugin(ResolvedVc::cell(Box::new(NextServerActions {
             transform,
             encryption_key,
-            dynamic_io_enabled,
+            use_cache_enabled,
             cache_kinds,
         }) as _));
     ModuleRule::new(
@@ -44,7 +44,7 @@ pub fn get_server_actions_transform_rule(
 struct NextServerActions {
     transform: ActionsTransform,
     encryption_key: ResolvedVc<RcStr>,
-    dynamic_io_enabled: bool,
+    use_cache_enabled: bool,
     cache_kinds: ResolvedVc<CacheKinds>,
 }
 
@@ -56,7 +56,7 @@ impl CustomTransformer for NextServerActions {
             &FileName::Real(ctx.file_path_str.into()),
             Config {
                 is_react_server_layer: matches!(self.transform, ActionsTransform::Server),
-                dynamic_io_enabled: self.dynamic_io_enabled,
+                use_cache_enabled: self.use_cache_enabled,
                 hash_salt: self.encryption_key.await?.to_string(),
                 cache_kinds: self.cache_kinds.await?.clone_value(),
             },

diff --git a/crates/next-custom-transforms/src/transforms/server_actions.rs b/crates/next-custom-transforms/src/transforms/server_actions.rs
@@ -31,7 +31,7 @@ use turbo_rcstr::RcStr;
 #[serde(deny_unknown_fields, rename_all = "camelCase")]
 pub struct Config {
     pub is_react_server_layer: bool,
-    pub dynamic_io_enabled: bool,
+    pub use_cache_enabled: bool,
     pub hash_salt: String,
     pub cache_kinds: FxHashSet<RcStr>,
 }
@@ -104,7 +104,7 @@ enum ServerActionsErrorKind {
         span: Span,
         cache_kind: RcStr,
     },
-    UseCacheWithoutDynamicIO {
+    UseCacheWithoutExperimentalFlag {
         span: Span,
         directive: String,
     },
@@ -2684,8 +2684,8 @@ impl DirectiveVisitor<'_> {
                             location: self.location.clone(),
                         });
                     } else if self.is_allowed_position {
-                        if !self.config.dynamic_io_enabled {
-                            emit_error(ServerActionsErrorKind::UseCacheWithoutDynamicIO {
+                        if !self.config.use_cache_enabled {
+                            emit_error(ServerActionsErrorKind::UseCacheWithoutExperimentalFlag {
                                 span: *span,
                                 directive: value.to_string(),
                             });
@@ -3094,11 +3094,11 @@ fn emit_error(error_kind: ServerActionsErrorKind) {
                 "#
             },
         ),
-        ServerActionsErrorKind::UseCacheWithoutDynamicIO { span, directive } => (
+        ServerActionsErrorKind::UseCacheWithoutExperimentalFlag { span, directive } => (
             span,
             formatdoc! {
                 r#"
-                    To use "{directive}", please enable the experimental feature flag "dynamicIO" in your Next.js config.
+                    To use "{directive}", please enable the experimental feature flag "useCache" in your Next.js config.
 
                     Read more: https://nextjs.org/docs/canary/app/api-reference/directives/use-cache#usage
                 "#

diff --git a/crates/next-custom-transforms/tests/errors.rs b/crates/next-custom-transforms/tests/errors.rs
@@ -186,7 +186,7 @@ fn react_server_actions_server_errors(input: PathBuf) {
                     &FileName::Real("/app/item.js".into()),
                     server_actions::Config {
                         is_react_server_layer: true,
-                        dynamic_io_enabled: true,
+                        use_cache_enabled: true,
                         hash_salt: "".into(),
                         cache_kinds: FxHashSet::default(),
                     },
@@ -227,7 +227,7 @@ fn react_server_actions_client_errors(input: PathBuf) {
                     &FileName::Real("/app/item.js".into()),
                     server_actions::Config {
                         is_react_server_layer: false,
-                        dynamic_io_enabled: true,
+                        use_cache_enabled: true,
                         hash_salt: "".into(),
                         cache_kinds: FxHashSet::default(),
                     },
@@ -286,7 +286,7 @@ fn use_cache_not_allowed(input: PathBuf) {
                     &FileName::Real("/app/item.js".into()),
                     server_actions::Config {
                         is_react_server_layer: true,
-                        dynamic_io_enabled: false,
+                        use_cache_enabled: false,
                         hash_salt: "".into(),
                         cache_kinds: FxHashSet::from_iter(["x".into()]),
                     },

diff --git a/crates/next-custom-transforms/tests/errors/use-cache-not-allowed/1/output.stderr b/crates/next-custom-transforms/tests/errors/use-cache-not-allowed/1/output.stderr
@@ -1,4 +1,4 @@
-  x To use "use cache", please enable the experimental feature flag "dynamicIO" in your Next.js config.
+  x To use "use cache", please enable the experimental feature flag "useCache" in your Next.js config.
   | 
   | Read more: https://nextjs.org/docs/canary/app/api-reference/directives/use-cache#usage
   | 

diff --git a/crates/next-custom-transforms/tests/errors/use-cache-not-allowed/2/output.stderr b/crates/next-custom-transforms/tests/errors/use-cache-not-allowed/2/output.stderr
@@ -1,4 +1,4 @@
-  x To use "use cache: x", please enable the experimental feature flag "dynamicIO" in your Next.js config.
+  x To use "use cache: x", please enable the experimental feature flag "useCache" in your Next.js config.
   | 
   | Read more: https://nextjs.org/docs/canary/app/api-reference/directives/use-cache#usage
   | 

diff --git a/crates/next-custom-transforms/tests/fixture.rs b/crates/next-custom-transforms/tests/fixture.rs
@@ -567,7 +567,7 @@ fn server_actions_server_fixture(input: PathBuf) {
                     &FileName::Real("/app/item.js".into()),
                     server_actions::Config {
                         is_react_server_layer: true,
-                        dynamic_io_enabled: true,
+                        use_cache_enabled: true,
                         hash_salt: "".into(),
                         cache_kinds: FxHashSet::from_iter(["x".into()]),
                     },
@@ -601,7 +601,7 @@ fn next_font_with_directive_fixture(input: PathBuf) {
                     &FileName::Real("/app/test.tsx".into()),
                     server_actions::Config {
                         is_react_server_layer: true,
-                        dynamic_io_enabled: true,
+                        use_cache_enabled: true,
                         hash_salt: "".into(),
                         cache_kinds: FxHashSet::default(),
                     },
@@ -628,7 +628,7 @@ fn server_actions_client_fixture(input: PathBuf) {
                     &FileName::Real("/app/item.js".into()),
                     server_actions::Config {
                         is_react_server_layer: false,
-                        dynamic_io_enabled: true,
+                        use_cache_enabled: true,
                         hash_salt: "".into(),
                         cache_kinds: FxHashSet::default(),
                     },
@@ -931,7 +931,7 @@ fn test_source_maps(input: PathBuf) {
                     &FileName::Real("/app/item.js".into()),
                     server_actions::Config {
                         is_react_server_layer: true,
-                        dynamic_io_enabled: true,
+                        use_cache_enabled: true,
                         hash_salt: "".into(),
                         cache_kinds: FxHashSet::from_iter([]),
                     },

diff --git a/docs/01-app/04-api-reference/01-directives/use-cache.mdx b/docs/01-app/04-api-reference/01-directives/use-cache.mdx
@@ -6,6 +6,7 @@ related:
   title: Related
   description: View related API references.
   links:
+    - app/api-reference/config/next-config-js/useCache
     - app/api-reference/config/next-config-js/dynamicIO
     - app/api-reference/config/next-config-js/cacheLife
     - app/api-reference/functions/cacheTag
@@ -17,14 +18,14 @@ The `use cache` directive designates a component and/or a function to be cached.
 
 ## Usage
 
-Enable support for the `use cache` directive with the [`dynamicIO`](/docs/app/api-reference/config/next-config-js/dynamicIO) flag in your `next.config.ts` file:
+Enable support for the `use cache` directive with the [`useCache`](/docs/app/api-reference/config/next-config-js/useCache) flag in your `next.config.ts` file:
 
 ```ts filename="next.config.ts" switcher
 import type { NextConfig } from 'next'
 
 const nextConfig: NextConfig = {
   experimental: {
-    dynamicIO: true,
+    useCache: true,
   },
 }
 
@@ -35,13 +36,15 @@ export default nextConfig
 /** @type {import('next').NextConfig} */
 const nextConfig = {
   experimental: {
-    dynamicIO: true,
+    useCache: true,
   },
 }
 
 module.exports = nextConfig
 ```
 
+Additionally, `use cache` directives are also enabled when the [`dynamicIO`](/docs/app/api-reference/config/next-config-js/dynamicIO) flag is set.
+
 Then, you can use the `use cache` directive at the file, component, or function level:
 
 ```tsx
@@ -75,7 +78,6 @@ export async function getData() {
 - The return value of the cacheable function must also be serializable. This ensures that the cached data can be stored and retrieved correctly.
 - Functions that use the `use cache` directive must not have any side-effects, such as modifying state, directly manipulating the DOM, or setting timers to execute code at intervals.
 - If used alongside [Partial Prerendering](/docs/app/building-your-application/rendering/partial-prerendering), segments that have `use cache` will be prerendered as part of the static HTML shell.
-- The `use cache` directive will be available separately from the [`dynamicIO`](/docs/app/api-reference/config/next-config-js/dynamicIO) flag in the future.
 - Unlike [`unstable_cache`](/docs/app/api-reference/functions/unstable_cache) which only supports JSON data, `use cache` can cache any serializable data React can render, including the render output of components.
 
 ## Examples

diff --git a/docs/01-app/04-api-reference/05-config/01-next-config-js/useCache.mdx b/docs/01-app/04-api-reference/05-config/01-next-config-js/useCache.mdx
@@ -0,0 +1,29 @@
+---
+title: useCache
+description: Learn how to enable the useCache flag in Next.js.
+version: canary
+---
+
+The `useCache` flag is an experimental feature in Next.js that enables the [`use cache` directive](/docs/app/api-reference/directives/use-cache) to be used independently of [`dynamicIO`](/docs/app/api-reference/config/next-config-js/dynamicIO). When enabled, you can use `use cache` in your application even if `dynamicIO` is turned off.
+
+## Usage
+
+To enable the `useCache` flag, set it to `true` in the `experimental` section of your `next.config.ts` file:
+
+```ts filename="next.config.ts"
+import type { NextConfig } from 'next'
+
+const nextConfig: NextConfig = {
+  experimental: {
+    useCache: true,
+  },
+}
+
+export default nextConfig
+```
+
+When `useCache` is enabled, you can use the following cache functions and configurations:
+
+- The [`use cache` directive](/docs/app/api-reference/directives/use-cache)
+- The [`cacheLife` function](/docs/app/api-reference/config/next-config-js/cacheLife) with `use cache`
+- The [`cacheTag` function](/docs/app/api-reference/functions/cacheTag)
diff --git a/packages/next/errors.json b/packages/next/errors.json
@@ -624,5 +624,7 @@
   "623": "Invalid quality prop (%s) on \\`next/image\\` does not match \\`images.qualities\\` configured in your \\`next.config.js\\`\\nSee more info: https://nextjs.org/docs/messages/next-image-unconfigured-qualities",
   "624": "Internal Next.js Error: createMutableActionQueue was called more than once",
   "625": "Server Actions are not supported with static export.\\nRead more: https://nextjs.org/docs/app/building-your-application/deploying/static-exports#unsupported-features",
-  "626": "Intercepting routes are not supported with static export.\\nRead more: https://nextjs.org/docs/app/building-your-application/deploying/static-exports#unsupported-features"
+  "626": "Intercepting routes are not supported with static export.\\nRead more: https://nextjs.org/docs/app/building-your-application/deploying/static-exports#unsupported-features",
+  "627": "cacheLife() is only available with the experimental.useCache config.",
+  "628": "cacheTag() is only available with the experimental.useCache config."
 }
diff --git a/packages/next/src/build/static-paths/app.ts b/packages/next/src/build/static-paths/app.ts
@@ -304,7 +304,6 @@ export async function buildAppStaticPaths({
   const incrementalCache = await createIncrementalCache({
     dir,
     distDir,
-    dynamicIO,
     cacheHandler,
     cacheHandlers,
     requestHeaders,

diff --git a/packages/next/src/build/swc/options.ts b/packages/next/src/build/swc/options.ts
@@ -71,6 +71,7 @@ function getBaseSWCOptions({
   bundleLayer,
   isDynamicIo,
   cacheHandlers,
+  useCacheEnabled,
 }: {
   filename: string
   jest?: boolean
@@ -89,6 +90,7 @@ function getBaseSWCOptions({
   bundleLayer?: WebpackLayerName
   isDynamicIo?: boolean
   cacheHandlers?: ExperimentalConfig['cacheHandlers']
+  useCacheEnabled?: boolean
 }) {
   const isReactServerLayer = isWebpackServerOnlyLayer(bundleLayer)
   const isAppRouterPagesLayer = isWebpackAppPagesLayer(bundleLayer)
@@ -216,7 +218,7 @@ function getBaseSWCOptions({
       isAppRouterPagesLayer && !jest
         ? {
             isReactServerLayer,
-            dynamicIoEnabled: isDynamicIo,
+            useCacheEnabled,
             hashSalt: serverReferenceHashSalt,
             cacheKinds: cacheHandlers ? Object.keys(cacheHandlers) : [],
           }
@@ -364,6 +366,7 @@ export function getLoaderSWCOptions({
   bundleLayer,
   esm,
   cacheHandlers,
+  useCacheEnabled,
 }: {
   filename: string
   development: boolean
@@ -389,6 +392,7 @@ export function getLoaderSWCOptions({
   serverReferenceHashSalt: string
   bundleLayer?: WebpackLayerName
   cacheHandlers: ExperimentalConfig['cacheHandlers']
+  useCacheEnabled?: boolean
 }) {
   let baseOptions: any = getBaseSWCOptions({
     filename,
@@ -407,6 +411,7 @@ export function getLoaderSWCOptions({
     esm: !!esm,
     isDynamicIo,
     cacheHandlers,
+    useCacheEnabled,
   })
   baseOptions.fontLoaders = {
     fontLoaders: ['next/font/local', 'next/font/google'],

diff --git a/packages/next/src/build/utils.ts b/packages/next/src/build/utils.ts
@@ -1006,7 +1006,6 @@ export async function isPageStatic({
     cacheHandlers,
     distDir,
     dir,
-    dynamicIO,
     flushToDisk: isrFlushToDisk,
     cacheMaxMemorySize: maxMemoryCacheSize,
   })

diff --git a/packages/next/src/build/webpack/loaders/next-swc-loader.ts b/packages/next/src/build/webpack/loaders/next-swc-loader.ts
@@ -149,6 +149,7 @@ async function loaderTransform(
     bundleLayer,
     esm,
     cacheHandlers: nextConfig.experimental?.cacheHandlers,
+    useCacheEnabled: nextConfig.experimental?.useCache,
   })
 
   const programmaticOptions = {