This moves `experimental.cacheComponents` to a top level config. As part
of this, I disabled some tests in `build-output-prerender` that assert
on `cacheComponents` appearing in the experimental list. In a separate
PR, I'm going to show that Cache Components is enabled next to the
bundler info.
This also updates some docs pages to remove "experimental" language.
Currently we error if you cannot produce a shell unless you have a
Suspense boundary above the root. This is fine for normal IO but sync IO
like Math.random() and new Date() have much more significant bad
consequences for prerendering. Instead of treating these errors as
another flavor of "must have a shell" validation we should instead treat
them like they must be guarded behind something else dynamic like `await
connection()`.
In addition to unconditionally erroring for Sync IO in Server Components
when prerendering this change also removes the Sync IO warning for
runtime prefetches. This is because at the moment there is no way to
debug these errors in dev. In the future we will add validation for
prefetches and need to add back in some ability to warn for these cases
but until then we will leave this case as a silent deopt.
## What?
Rename `experimental.dynamicIO` to `experimental.cacheComponents` across
the Next.js codebase.
## Why?
We're going to be merging the functionality of the `ppr`, `dynamicIO`
and `useCache` experimental flags into the singular `cacheComponents`
flag to reduce complexity of the codebase and simplify adoption for
users wanting to experiment with experimental features.
## How?
- Renamed the configuration option from `experimental.dynamicIO` to
`experimental.cacheComponents`
- Added deprecation handling with automatic migration for the old option
name
- Updated all documentation, tests, and internal references
- Updated Rust code in SWC transforms and Turbopack
- Maintained backward compatibility with deprecation warnings
NAR-158
We want to respect the `__NEXT_EXPERIMENTAL_PPR` and `__NEXT_EXPERIMENTAL_CACHE_COMPONENTS` environment variables in the test apps, so that we can run them locally with these features enabled without needing to modify the config files.
So we're removing the requirement that `__NEXT_TEST_MODE` needs to be set at the same time. Usually you don't want to set this variable locally because it also changes other behavior in a few places.
This really has no downside, because it was already possible for users to set both variables and affect the flags, and now this can be done with a single variable. It allows us to keep the noise out of the test app's next config files.
We're also moving the assignments from the default config into `enforceExperimentalFeatures` to get the nice output when printing the experimental features in the CLI.
To prepare for an upcoming change where `ppr` will be enabled
automatically when `dynamicIO` is enabled, we're hard coding `ppr: true`
in the Dynamic IO tests with this PR. The non-PPR assertions are
subsequently removed, which makes up most of the changed lines.
We can now also exclude the tests in the PPR tests manifest, so that
they're not run twice in CI.
> [!NOTE]
> This PR is best reviewed with hidden whitespace changes.
This logs an error in dev and fails a build when using incompatible
segment configs (`dynamic`, `fetchCache`, `runtime`, `dynamicParams`)
with dynamicIO. It will point to all discovered pages that contained the
invalid segment config at the end of the build.
In dev, it will show the error in an overlay. The invalid segment
configs must be removed to build.
Note: This removes all incompatible test cases that were previously part
of the `dynamic-io` test suites, and disables one that was using a
fetchCache workaround until it's properly handled.
`Math.random()` is IO though it is synchronous. When `dynamicIO` is
enabled we need to treat calls to `Math.random()` as IO and exclude them
from prerenders unless they are cached. This change sets up the
instrumentation for this behavior.
Unless the sync access of async request APIs this patch does not yet
have any dev warnings. These will be added in a future update when we
can instrument the environment name during dev to tell the difference
between the prerender phase, and render phase even without a build
Zack Tanner