docs(cloudflare): perf tips #185
There are no files selected for viewing
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 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 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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,99 @@ | ||
| import { Callout } from "nextra/components"; | ||
|
|
||
| ## Performance tips | ||
|
|
||
| They are a lot of features and knobs you can tune to improve the performance of your app. This page lists some of the recommend settings. | ||
|
|
||
| ### General | ||
|
|
||
| You should regularly update to the latest available version of [`@opennextjs/cloudflare`](https://www.npmjs.com/package/@opennextjs/cloudflare) to benefit from the latest performance and security updates. | ||
|
|
||
| ### Caching | ||
|
|
||
| Caching can drastically improves the performance of your application by only fetching data / re-generating your pages when they change. | ||
|
|
||
| To get the most out of caching, you should start by reading how Next.js implements caching. The ["Caching in Next.js" guide](https://nextjs.org/docs/app/guides/caching) is a good place to start. | ||
|
|
||
| You should then check [how to configure caching](/cloudflare/caching) for the OpenNext adapter. See below for some advice. | ||
|
|
||
| #### [Incremental Cache](/cloudflare/caching#incremental-static-regeneration-isr) | ||
|
|
||
| The Incremental cache is the store containing all the cached data (i.e. pages, `fetch`, `unstable_cache`). | ||
|
|
||
| You should use the Workers Static Assets based cache if your site is SSG. It is the fastest available option. Note that as Workers Static Assets are read-only, this option can not be used with revalidation. | ||
|
|
||
| When your app uses re-validation, use the R2 based store instead. We recommend the following settings to get the best perfomance: | ||
|
|
||
| - use regional cache by wrapping the handler into `withRegionalCache(...)` | ||
| - use the `long-lived` mode | ||
| - you should not need to explicitly set `shouldLazilyUpdateOnCacheHit` nor `bypassTagCacheOnCacheHit` as they are set to the most performant mode by default | ||
| - setup [automatic cache purge](/cloudflare/caching#automatic-cache-purge) | ||
|
|
||
| <Callout type="info"> | ||
| Using KV is not recommended as it is eventually consistent. It could cause stale data to be persisted | ||
| indefinitely | ||
| </Callout> | ||
|
|
||
| #### [Tag Cache](/cloudflare/caching#tag-cache-for-on-demand-revalidation) | ||
|
|
||
| The Tag Cache is not properly a cache. It only stores the timestamp at which tags have been revalidated. | ||
|
|
||
| It should be configured for App-Router based app using `revalidateTag` or `revalidatePath`. | ||
|
|
||
| The D1 based tag cache should only be used if your site receives low traffic. The Durable Object based tag cache is the recommend option for most sites. See [the reference guide](/cloudflare/caching#tag-cache-for-on-demand-revalidation) for the available configuration options. | ||
|
There was a problem hiding this comment. Should we say low traffic ? Do we want to add some numbers here ? I feel like a lot of people just testing OpenNext should use D1 |
||
|
|
||
|
There was a problem hiding this comment. We should definitely add some notes here about the DO tag cache around the sizing of it, a lot of people issues with that is probably about bad sizing actually. Maybe in another PR, because it is a big subject |
||
| Application using `revalidateTag` exclusively (and not `revalidatePath`) will benefit from using the `withFilter` wrapper with the `softTagFilter` filter. | ||
|
|
||
| #### [Static Assets](/cloudflare/caching#static-assets-caching) | ||
|
|
||
| You should add a `public/_headers` file to cache the static assets served by your app. | ||
|
|
||
| See the [Cloudflare documentation](https://developers.cloudflare.com/workers/static-assets/headers/) for a detailed explanation of the default and the syntax. | ||
|
|
||
| ### [Multiple Workers](https://opennext.js.org/cloudflare/howtos/multi-worker) | ||
|
|
||
| Deploying the middleware and the main server to distinct Workers can help with performance. As when a page can be retrieved from the cache, the main server can be fully bypassed. | ||
|
|
||
| ### Troubleshooting performance | ||
|
|
||
| You can profile the code to troubleshoot performance issues. | ||
|
|
||
| #### Building unminified code | ||
|
|
||
| Code profiles are much easier to read when the code is not minified, you can use the following settings to generate unminified code | ||
|
|
||
| **next.config.ts** | ||
|
|
||
| ```ts | ||
| const nextConfig = { | ||
| // ... | ||
| experimental: { | ||
| serverMinification: false, | ||
| }, | ||
| webpack: (config) => { | ||
| config.optimization.minimize = false; | ||
| return config; | ||
| }, | ||
| compress: false, | ||
| }; | ||
| ``` | ||
|
|
||
| **CLI** | ||
|
|
||
| Use the `--noMinify` option when building the app: | ||
|
|
||
| ```bash | ||
| opennextjs-cloudflare build --noMinify | ||
| ``` | ||
|
|
||
| #### Record a profile | ||
|
|
||
| You should first launch a local version of your application by running | ||
|
|
||
| ```bash | ||
| opennextjs-cloudflare preview | ||
| ``` | ||
|
|
||
| Once the app is running, follow [the steps from the Workers doc](https://developers.cloudflare.com/workers/observability/dev-tools/cpu-usage/) to record a CPU profile. | ||
|
|
||
| You can then inspect the profile and check if any particular section of the application is unexpectedly slow. | ||
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
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
We could add a note about the data cache here, you could use static assets if you only have SSG route (that you don't revalidate) and SSR route with absolutely no data cache (or one that don't change after build).
If they use that they should also not use the tag cache