Unverified Commit fc5ebd29 authored by Aurora Scharff's avatar Aurora Scharff Committed by GitHub

docs: clarify use cache is unsupported in Proxy (#100842)

## Summary

- document that Proxy does not transform `use cache` or `use server`;
functions still execute, but directive semantics do not apply
- explain that `use cache` output is neither cached nor deduplicated in
Proxy and that `cacheLife` throws without a cache scope
- clarify that hosting providers can replace the default cache handler
or disable runtime storage, while concurrent calls can still be
deduplicated
- point Proxy users to an external cache or data store, or to a
supported application context such as a Server Component or Route
Handler

Affected documentation:

- `docs/01-app/01-getting-started/16-proxy.mdx`
- `docs/01-app/03-api-reference/03-file-conventions/proxy.mdx` (also
supplies the Pages Router Proxy reference)
- `docs/01-app/03-api-reference/01-directives/use-cache.mdx`
- `docs/01-app/03-api-reference/01-directives/use-server.mdx`

Related to #85475.
Finding: https://next-maintainer-agent.vercel.tools/agent-feedback/5487

## Verification

- Prettier 3.6.2 check on the changed MDX files
- `git diff --cached --check` before committing
- Not run: test suite (documentation-only change)

<!-- NEXT_JS_LLM -->

---------
Co-authored-by: 's avatarJoseph <joseph.chamochumbi@vercel.com>
Co-authored-by: 's avatarJoseph <sephxd1234@gmail.com>
parent a14cbc44
......@@ -26,9 +26,13 @@ Some common scenarios where Proxy is effective include:
For simple redirects, consider using the [`redirects`](/docs/app/api-reference/config/next-config-js/redirects) configuration in `next.config.ts` first. Proxy should be used when you need access to request data or more complex logic.
### Limitations
Proxy is _not_ intended for slow data fetching. While Proxy can be helpful for [optimistic checks](/docs/app/guides/authentication#optimistic-checks-with-proxy-optional) such as permission-based redirects, it should not be used as a full session management or authorization solution.
Using fetch with `options.cache`, `options.next.revalidate`, or `options.next.tags`, has no effect in Proxy.
Directives such as [`use cache`](/docs/app/api-reference/directives/use-cache) and [`use server`](/docs/app/api-reference/directives/use-server) have no effect in Proxy, because Proxy does not apply [directive transforms](/docs/app/api-reference/directives).
`fetch` options such as `cache`, `next.revalidate`, and `next.tags` also do not cache responses. To reuse cached data in Proxy, use an [external cache or data store](/docs/app/guides/redirecting#managing-redirects-at-scale-advanced). Alternatively, move the work to a supported context, such as a Server Component or Route Handler.
### Convention
......
......@@ -253,7 +253,9 @@ With the default in-memory handler, runtime cache behavior depends on your hosti
For example, in a serverless environment, a cached function shared by two pages executes on each static shell revalidation, whereas in self-hosted or environments with persistent memory, the cached output is reused if it's still fresh.
If the default in-memory cache isn't enough, consider **[`use cache: remote`](/docs/app/api-reference/directives/use-cache-remote)** which allows platforms to provide a dedicated cache handler (like Redis or KV database). This helps reduce hits against data sources not scaled to your total traffic, though it comes with costs (storage, network latency, platform fees).
Hosting providers can replace the default cache handler, and some do not store `use cache` output at runtime. Values computed during prerendering are still reused by later requests, but values computed at request time are not. Check your hosting provider's documentation for its runtime caching behavior.
If the default in-memory cache isn't enough, or your provider does not store runtime output, consider **[`use cache: remote`](/docs/app/api-reference/directives/use-cache-remote)** which allows platforms to provide a dedicated cache handler (like Redis or KV database). This helps reduce hits against data sources not scaled to your total traffic, though it comes with costs (storage, network latency, platform fees).
> [!NOTE]
> With the default in-memory handler, serverless instances are ephemeral, so entries may not be reused between requests, unlike with `use cache: remote`. Neither caching directive carries over to a new deploy, because the [cache key](#cache-keys) includes the build (or `deploymentId`) ID.
......@@ -417,6 +419,10 @@ export async function getData() {
}
```
[Proxy](/docs/app/api-reference/file-conventions/proxy) does not apply [directive transforms](/docs/app/api-reference/directives), so `use cache` has no effect in Proxy. A function that is cached elsewhere in your application runs as an ordinary function when Proxy imports it.
Calling [`cacheLife`](/docs/app/api-reference/functions/cacheLife) or [`cacheTag`](/docs/app/api-reference/functions/cacheTag) in that function throws because Proxy does not create a cache scope.
### Caching a component's output with `use cache`
You can use `use cache` at the component level to cache any fetches or computations performed within that component. The cache entry will be reused as long as the serialized props produce the same value in each instance.
......
......@@ -7,6 +7,8 @@ The `use server` directive designates a function or file to be executed on the *
For Next.js-specific Server Action behaviors (response model, security, configuration, deployment), see [Server Actions and Mutations](/docs/app/guides/server-actions).
> **Good to know**: [Proxy](/docs/app/api-reference/file-conventions/proxy) does not apply [directive transforms](/docs/app/api-reference/directives), so `use server` has no effect in Proxy. A function that is a Server Function elsewhere in your application runs as an ordinary function when Proxy imports it.
## Using `use server` at the top of a file
The following example shows a file with a `use server` directive at the top. All functions in the file are executed on the server.
......
......@@ -18,6 +18,8 @@ Proxy executes before routes are rendered. It's particularly useful for implemen
>
> Proxy is meant to be invoked separately of your render code and in optimized cases deployed to your CDN for fast redirect/rewrite handling, you should not attempt relying on shared modules or globals.
>
> See [Proxy limitations](/docs/app/getting-started/proxy#limitations) for unsupported directive and caching behavior.
>
> To pass information from Proxy to your application, use [headers](#setting-headers), [cookies](#using-cookies), [rewrites](/docs/app/api-reference/functions/next-response#rewrite), [redirects](/docs/app/api-reference/functions/next-response#redirect), or the URL.
Create a `proxy.ts` (or `.js`) file in the project root, or inside `src` if applicable, so that it is located at the same level as `pages` or `app`.
......
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