[turbopack] Update next docs with information about turbopack known adoption issues #82560
+77
−5
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This stack of pull requests is managed by Graphite. Learn more about stacking. |
lukesandberg
changed the title
![graphite-app[bot]](https://avatars.githubusercontent.com/in/158384?s=60&v=4){kind=small}
mischnic
reviewed
Aug 12, 2025
icyJoseph
reviewed
Aug 12, 2025
|
|
||
| ## Usage | ||
|
|
||
| Turbopack Persistent Caching enables turbopack to share state across multiple `next dev` or `next build` commands. When enabled, Turbopack will save and restore data to the `.next` folder between builds, which can greatly speed up builds. |
There was a problem hiding this comment.
Asking for my own clarity here first
- A sequence of
next dev->next devhits the Persistent Cache - A sequence of
next dev->next build, wouldn't hit the cache for the build step, right? Or I guess, it'd miss it because it wouldn't hit production assets? - A sequence
next build->next dev->next buildfor the 3rd command, would hit cached elements from the 1st, or?
If so, maybe we can reword
Suggested change
| Turbopack Persistent Caching enables turbopack to share state across multiple `next dev` or `next build` commands. When enabled, Turbopack will save and restore data to the `.next` folder between builds, which can greatly speed up builds. | |
| Turbopack Persistent Caching lets multiple `next dev` runs share state, and likewise for `next build` runs. When enabled, Turbopack stores data in the `.next` folder and reuses it between matching command runs, greatly speeding them up. |
There was a problem hiding this comment.
next dev and next build can share the cache. The cache hit rates won't always be super high between these two but they aren't nothing. (e.g. most resolve results and many basic parsing tasks are identical)
There was a problem hiding this comment.
Not sure about that to be honest.
For resolving, the exports conditions are different.
For parsing, the environment variables are part of the cache key and the JSX AST transform is different in dev/prod.
There was a problem hiding this comment.
well i guess we can at least share the file reads 😭 and i suppose since the keys are different a next build won't destroy the next dev cache, they just aren't sharing much....
ijjk
added
created-by: Turbopack team
lukesandberg
force-pushed
the
bundle_size
branch
from
f0df7d9 to
120178e
Compare
|
All broken links are now fixed, thank you! |
![vercel[bot]](https://avatars.githubusercontent.com/in/8329?s=60&v=4){kind=small}
docs/01-app/03-api-reference/05-config/01-next-config-js/turbopackPersistentCaching.mdx
Outdated
Show resolved
Hide resolved
lukesandberg
added a commit
that referenced
this pull request
Aug 13, 2025
Drop the scare text about not running turbopack in production. Instead clarify that builds are beta and direct people to our documentation site. For example:  Compared to the old notice:  Notably * mission critical applications are a good idea! just be careful with compatibility issues * the source maps issues is fixed! no need to talk about it at all * A discussion of bundle size issues and build caches is being added in #82560 Closes PACK-5237
lukesandberg
force-pushed
the
bundle_size
branch
from
7f3a5a2 to
938730a
Compare
mischnic
reviewed
Aug 13, 2025
Comment on lines
+7
to
+31
| ## Usage | ||
|
|
||
| Turbopack Persistent Caching enables Turbopack to share state across multiple `next dev` or `next build` commands. When enabled, Turbopack will save and restore data to the `.next` folder between builds, which can greatly speed up subsequent builds and dev sessions. | ||
|
|
||
| ```ts filename="next.config.ts" switcher | ||
| import type { NextConfig } from 'next' | ||
|
|
||
| const nextConfig: NextConfig = { | ||
| experimental: { | ||
| turbopackPersistentCaching: true, | ||
| }, | ||
| } | ||
|
|
||
| export default nextConfig | ||
| ``` | ||
|
|
||
| ```js filename="next.config.js" switcher | ||
| /** @type {import('next').NextConfig} */ | ||
| const nextConfig = { | ||
| experimental: { | ||
| turbopackPersistentCaching: true, | ||
| }, | ||
| } | ||
|
|
||
| module.exports = nextConfig |
There was a problem hiding this comment.
Should this contain a warning that this really really isn't stable yet (though there's experimental already in there of course)?
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
innerGraphoptimizationWill wait to submit this until the when we publish the release.