Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Docs: Address internal use cache comments #71981

Merged
merged 4 commits into from
Oct 29, 2024
Merged

Docs: Address internal use cache comments #71981

merged 4 commits into from
Oct 29, 2024
+13 −15

Conversation

delbaoliveira
Copy link
Contributor

@ijjk ijjk added created-by: Next.js DevEx team Documentation Related to Next.js' official documentation. labels Oct 28, 2024
@delbaoliveira delbaoliveira changed the title Docs: Address internal use cache feedback Docs: Address internal use cache comments Oct 28, 2024
gaearon
gaearon reviewed Oct 28, 2024
View reviewed changes
docs/02-app/02-api-reference/01-directives/use-cache.mdx
3. Inner caches at two levels deep, do not affect the outer cache since they have already provided their duration to their parent.
1. Next.js will use the shortest cache profile found within the whole `use cache` boundary, excluding inner `use cache` directives.
2. If no cache profile exists, then the shortest profile times from all inner `use cache` calls applies to this `use cache`. If there are no inner `use cache`'s then the default is used
3. Inner caches at two levels deep do not affect the outer cache since they have already provided their duration to their parent.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have to say I still don't have a clear understanding of the nested behavior. There is an example below but it doesn't actually show what's going to happen. The way I'm reading it now, I assume that ChildComponent will be days-stale in the context of ParentComponent (due to the outer boundary, rule #1) but would be hours-stale if it was rendered on its own. Is that the expectation? This should ideally be spelled out just below the example — the code comment seems to contradict that.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The constraints I care about as an app author:

  • When I give a cache lifetime to the child, do I have a guarantee it will update at least as often? Even if that forces everything above to invalidate?
  • Or does the outer scope "win" and outer scope can "freeze" inner scopes that would've liked to revalidate more often?
  • When I want to avoid this conflict, how do I break out of it? (I assume via the children composition trick instead of nested scopes?)

It would be good to write this part from this perspective. The concerns that need to be addressed is (1) is my stuff ever going to be more stale than locally expected, (2) is my stuff going to revalidate more often than locally expected, (3) how to resolve conflicts between expectations if there's a clear "hole" that can be cut.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you for the feedback Dan, I'll address this and other community questions in a follow-up PR. 🙏🏼

@delbaoliveira delbaoliveira merged commit 256b662 into canary Oct 29, 2024
50 checks passed
@delbaoliveira delbaoliveira deleted the docs-8d7f branch October 29, 2024 13:32
renovate bot added a commit to mmkal/eslint-plugin-mmkal that referenced this pull request Oct 29, 2024
@renovate
fix(deps): update dependency @next/eslint-plugin-next to v15.0.2
331f65e 
##### [v15.0.2](https://github.com/vercel/next.js/releases/tag/v15.0.2)

##### Core Changes

-   Read page name from work store in server module map proxy: [#71669](vercel/next.js#71669)
-   codemod: should not transform when param is not used: [#71664](vercel/next.js#71664)
-   \[dynamicIO] complete refactor to prerender: [#71687](vercel/next.js#71687)
-   fix: metadata image route normalize path posix for windows: [#71673](vercel/next.js#71673)
-   next-codemod(upgrade): optional catch when missing dev script: [#71598](vercel/next.js#71598)
-   Avoid server action function indirection in Turbopack: [#71628](vercel/next.js#71628)
-   fix: exclude `basePath` in `findSourceMapURL`: [#71719](vercel/next.js#71719)
-   fix: stack frame text color in dark mode: [#71656](vercel/next.js#71656)
-   Fix: revert the bad node binary handling: [#71723](vercel/next.js#71723)
-   next-codemod: add empty `pnpm-workspace.yaml` to test fixtures to bypass PNPM workspace checks: [#71726](vercel/next.js#71726)
-   warn on sync access if dynamicIO is not enabled: [#71696](vercel/next.js#71696)
-   Update React from `69d4b800-20241021` to `45804af1-20241021`: [#71718](vercel/next.js#71718)
-   next-upgrade: do not add `--turbopack` flag when `--turbo` exists in `next dev`: [#71730](vercel/next.js#71730)
-   feat: stitch errors with react owner stack: [#70393](vercel/next.js#70393)
-   \[dynamicIO] update data access error and documentation: [#71738](vercel/next.js#71738)
-   Test cached form action with revalidate: [#71591](vercel/next.js#71591)
-   Upgrade React from `45804af1-20241021` to `28668d39-20241023`: [#71745](vercel/next.js#71745)
-   Fix race condition when setting client reference manifests: [#71741](vercel/next.js#71741)
-   Fix fetch with no-store inside of use cache: [#71754](vercel/next.js#71754)
-   Remove the bottom collapse button in dev overlay: [#71658](vercel/next.js#71658)
-   \[dynamicIO] unify cache filling and lazy-module warming: [#71749](vercel/next.js#71749)
-   Don't filter out <anonymous> source location frames through RSC: [#71752](vercel/next.js#71752)
-   fix undefined default export error msg: [#71762](vercel/next.js#71762)
-   Upgrade React from `28668d39-20241023` to `1631855f-20241023`: [#71769](vercel/next.js#71769)
-   Enable owner stack in experimental build: [#71716](vercel/next.js#71716)
-   feat: add experiment for sharpjs cpu flags: [#71733](vercel/next.js#71733)
-   fix: handle server component replay error in error overlay: [#71772](vercel/next.js#71772)
-   Don't error asking for prebuilt bundles: [#71778](vercel/next.js#71778)
-   Replace `turbopack://[project]/...` sourcemap uris with `file://...` in development: [#71489](vercel/next.js#71489)
-   misc: update source map paths for bundled Next.js runtime: [#71779](vercel/next.js#71779)
-   \[dynamicIO] refine error message and docs: [#71781](vercel/next.js#71781)
-   next-upgrade: change `--turbo` to `--turbopack` if applicable: [#71737](vercel/next.js#71737)
-   Show all diff when uncollapse: [#71792](vercel/next.js#71792)
-   Sourcemap errors in terminal by default : [#71444](vercel/next.js#71444)
-   Fully enable custom error callbacks for app router: [#71794](vercel/next.js#71794)
-   Simplify Server Action Webpack plugin: [#71721](vercel/next.js#71721)
-   ensure DIO development segment errors are cleared after correcting: [#71811](vercel/next.js#71811)
-   Include sourceframe in errors logged in the terminal during development: [#71803](vercel/next.js#71803)
-   \[dynamicIO] update prerender cache scoping and cache warming for validation: [#71822](vercel/next.js#71822)
-   only force stack frame color in tty: [#71860](vercel/next.js#71860)
-   Add test for fetch with auth in use cache: [#71768](vercel/next.js#71768)
-   Fix race with hot-reloader-client clearing overlay errors: [#71771](vercel/next.js#71771)
-   Fix dynamic tracking in dev: [#71867](vercel/next.js#71867)
-   Revert "Sourcemap errors in terminal by default ([#71444](vercel/next.js#71444))": [#71868](vercel/next.js#71868)
-   Fix fetch caching inside of `"use cache"`: [#71793](vercel/next.js#71793)
-   Trace upload: only send traces for current session: [#71838](vercel/next.js#71838)
-   Reland "Sourcemap errors in terminal by default": [#71877](vercel/next.js#71877)
-   Implement information byte in Server Reference ID and other optimizations: [#71463](vercel/next.js#71463)
-   fix: webpack build error on Windows: [#71943](vercel/next.js#71943)
-   Run with `--enable-source-maps` by default in `next dev`: [#71820](vercel/next.js#71820)
-   fix global-error styles: [#71914](vercel/next.js#71914)
-   Use `registerClientReference` for ESM client component modules: [#71968](vercel/next.js#71968)
-   Fix missing `await` of `params` when metadata is used with an image file: [#71871](vercel/next.js#71871)
-   Upgrade React from `1631855f-20241023` to `02c0e824-20241028`: [#71979](vercel/next.js#71979)
-   Populate sourcemap `ignoreList` when Webpack is used: [#71821](vercel/next.js#71821)
-   \[dynamicIO] unify server and client prerender for non-ppr pathway: [#71764](vercel/next.js#71764)
-   codemod: add separator to the parenthenese expr: [#71993](vercel/next.js#71993)
-   Respect sourcemap's ignore list when printing errors in the terminal: [#71908](vercel/next.js#71908)
-   fix console color to be compatible in chrome devtools: [#71939](vercel/next.js#71939)
-   Delete obsolete codemod `next-dynamic-access-named-export`: [#72016](vercel/next.js#72016)
-   fix: log the error instance modified extra location info: [#71930](vercel/next.js#71930)
-   Compare error stack to dedupe error: [#71798](vercel/next.js#71798)

##### Example Changes

-   experimental.instrumentationHook is not necessary anymore: [#71808](vercel/next.js#71808)
-   Add Jude to nextjs team: [#71936](vercel/next.js#71936)

##### Misc Changes

-   docs: fix broken link in Architecture/Turbopack documentation: [#71412](vercel/next.js#71412)
-   test: migrate rest async api usage in tests: [#71663](vercel/next.js#71663)
-   fix: docs for dynamic routing in next 15: [#71531](vercel/next.js#71531)
-   Remove the 'new' keyword from the GET function sample code.: [#71671](vercel/next.js#71671)
-   chore: fix wrong path of comments: [#71682](vercel/next.js#71682)
-   docs(next-config): remove mention of appIsrStatus is on canary: [#71695](vercel/next.js#71695)
-   react-sync: Ignore update notices from npm: [#71717](vercel/next.js#71717)
-   Docs: Update default marker for fetch cache option: [#71728](vercel/next.js#71728)
-   \[docs] Fix page.tsx parameter types: [#71680](vercel/next.js#71680)
-   \[docs] Fix table.js containing TS code: [#71677](vercel/next.js#71677)
-   docs(ppr): update note about ppr: [#71697](vercel/next.js#71697)
-   docs lint: [#71748](vercel/next.js#71748)
-   fixes error message asserts and lints: [#71747](vercel/next.js#71747)
-   Fix docs for configuring Turbopack: [#71755](vercel/next.js#71755)
-   docs(turbo): add experimental icon to turbo config section: [#71761](vercel/next.js#71761)
-   feat(turbopack): Add `__turbopack_original__` while tree shaking: [#71547](vercel/next.js#71547)
-   test: re-enable test with note: [#71789](vercel/next.js#71789)
-   Docs: Remove beta marker from Turbopack docs: [#71796](vercel/next.js#71796)
-   Update docs 1: [#71812](vercel/next.js#71812)
-   docs lint fixes: [#71813](vercel/next.js#71813)
-   docs: remove `"use cache"` on before code snippet: [#71815](vercel/next.js#71815)
-   Next docs broken links: [#71823](vercel/next.js#71823)
-   \[Turbopack] add optimization based on upper count: [#71606](vercel/next.js#71606)
-   chore(turbo-tasks-backend): Use let instead of match for macro bindings: [#71756](vercel/next.js#71756)
-   chore(turbo-tasks-backend): Remove collapsible-if lints: [#71758](vercel/next.js#71758)
-   removing extra reference: [#71853](vercel/next.js#71853)
-   codemod(turbopack): Rewrite Vc fields in structs as ResolvedVc (part 3): [#71665](vercel/next.js#71665)
-   Update sync-dynamic-apis.mdx: [#71907](vercel/next.js#71907)
-   codemod(turbopack): Rewrite Vc fields in structs as ResolvedVc (part 4): [#71804](vercel/next.js#71804)
-   test: remove duplicated flaky test: [#71967](vercel/next.js#71967)
-   docs: Fix typo in cacheLife configs in use-cache docs: [#71921](vercel/next.js#71921)
-   Fix use cache example line highlights: [#71883](vercel/next.js#71883)
-   Allow breakpoints to be set in `packages/next/src/compiled`: [#71986](vercel/next.js#71986)
-   updated upgrade to v15 command in docs: [#71643](vercel/next.js#71643)
-   codemod(turbopack): Rewrite Vc fields in structs as ResolvedVc (part 5): [#71861](vercel/next.js#71861)
-   Clarify that streaming is blocked on generateMetadata for initial load: [#71985](vercel/next.js#71985)
-   Docs: Add legacy tags: [#71964](vercel/next.js#71964)
-   Docs: Fix broken link: [#72021](vercel/next.js#72021)
-   (docs) `use cache`: Add text code formatting: [#71999](vercel/next.js#71999)
-   docs: update file structure: [#71951](vercel/next.js#71951)
-   Documentation Fix: Correct `cacheTag` Function Usage: [#71912](vercel/next.js#71912)
-   correct expire calc & and Nested usage import in use-cache docs: [#71899](vercel/next.js#71899)
-   Docs: Address internal `use cache` comments : [#71981](vercel/next.js#71981)
-   Fix swc version mismatch when checking out an older version: [#71978](vercel/next.js#71978)

##### Credits

Huge thanks to [@ytori](https://github.com/ytori), [@unstubbable](https://github.com/unstubbable), [@huozhi](https://github.com/huozhi), [@SebassNoob](https://github.com/SebassNoob), [@tatsuteb](https://github.com/tatsuteb), [@Marukome0743](https://github.com/Marukome0743), [@gnoff](https://github.com/gnoff), [@samcx](https://github.com/samcx), [@devjiwonchoi](https://github.com/devjiwonchoi), [@imprakharshukla](https://github.com/imprakharshukla), [@migueldamota](https://github.com/migueldamota), [@eps1lon](https://github.com/eps1lon), [@ztanner](https://github.com/ztanner), [@timneutkens](https://github.com/timneutkens), [@cantemizyurek](https://github.com/cantemizyurek), [@sebmarkbage](https://github.com/sebmarkbage), [@padmaia](https://github.com/padmaia), [@ijjk](https://github.com/ijjk), [@styfle](https://github.com/styfle), [@wbinnssmith](https://github.com/wbinnssmith), [@feedthejim](https://github.com/feedthejim), [@kdy1](https://github.com/kdy1), [@shuding](https://github.com/shuding), [@molebox](https://github.com/molebox), [@ismaelrumzan](https://github.com/ismaelrumzan), [@sokra](https://github.com/sokra), [@bgw](https://github.com/bgw), [@timeyoutakeit](https://github.com/timeyoutakeit), [@AdonisAgelis](https://github.com/AdonisAgelis), [@chicoxyzzy](https://github.com/chicoxyzzy), [@gaojude](https://github.com/gaojude), [@elitalpa](https://github.com/elitalpa), [@t3dotgg](https://github.com/t3dotgg), [@gaearon](https://github.com/gaearon), [@nisabmohd](https://github.com/nisabmohd), [@gadcam](https://github.com/gadcam), [@delbaoliveira](https://github.com/delbaoliveira), [@bennettdams](https://github.com/bennettdams), [@wiscaksono](https://github.com/wiscaksono), and [@Developerayo](https://github.com/Developerayo) for helping!
kdy1 pushed a commit that referenced this pull request Oct 30, 2024
@delbaoliveira @kdy1
Docs: Address internal use cache comments (#71981)
c944da3 
Related:
https://linear.app/vercel/issue/NDX-402/address-use-cache-feedback

Thank you for the review
[@timeyoutakeit](https://github.com/timeyoutakeit) ❤️
stipsan pushed a commit to sanity-io/next.js that referenced this pull request Nov 6, 2024
@delbaoliveira @stipsan
Docs: Address internal use cache comments (vercel#71981)
a3ddbe7 
Related:
https://linear.app/vercel/issue/NDX-402/address-use-cache-feedback

Thank you for the review
[@timeyoutakeit](https://github.com/timeyoutakeit) ❤️
@github-actions github-actions bot locked as resolved and limited conversation to collaborators Nov 13, 2024
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Reviewers

@gaearon gaearon gaearon left review comments

@ismaelrumzan ismaelrumzan ismaelrumzan left review comments

@timeyoutakeit timeyoutakeit timeyoutakeit approved these changes

Assignees
No one assigned
Labels
created-by: Next.js DevEx team Documentation Related to Next.js' official documentation. locked
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
5 participants
@delbaoliveira @ismaelrumzan @gaearon @timeyoutakeit @ijjk