From 9c85f21f653234a5a051a100cef0eaab35a0272d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Benjam=C3=ADn=20Vicente?= Date: Fri, 2 May 2025 13:53:24 -0400 Subject: [PATCH 1/5] docs(cloudflare): add static assets caching --- pages/cloudflare/caching.mdx | 16 ++++++++++++++++ pages/cloudflare/get-started.mdx | 23 +++++++++++++++++------ 2 files changed, 33 insertions(+), 6 deletions(-) diff --git a/pages/cloudflare/caching.mdx b/pages/cloudflare/caching.mdx index 92d5907..cf6f378 100644 --- a/pages/cloudflare/caching.mdx +++ b/pages/cloudflare/caching.mdx @@ -212,6 +212,22 @@ For staging, when your site receives low traffic from a single IP, you can repla ### References +#### Static Assets Caching + + + The worker doesn't run **in front** of static assets, so `next.config.js` `headers` option doesn't apply to + public files (`public`) and static build files (like `_next/static`). + + +By default, Cloudflare [Static Assets headers](https://developers.cloudflare.com/workers/static-assets/headers/#default-headers) don't enable browser caching. To add browser cache headers or any custom headers to Static Assets, create a `public/_headers` file: + +```txt +/_next/static/* + Cache-Control: public,max-age=31536000,immutable +``` + +Internal usage of Static Assets, such as for ISR where assets aren't sent directly to the browser, isn’t affected. + #### Incremental Static Regeneration (ISR) There are 3 storage options for the incremental cache: diff --git a/pages/cloudflare/get-started.mdx b/pages/cloudflare/get-started.mdx index 454d474..9626378 100644 --- a/pages/cloudflare/get-started.mdx +++ b/pages/cloudflare/get-started.mdx @@ -138,21 +138,32 @@ Add the following to the scripts field of your `package.json` file: - `npm run upload`: Builds your app, and then uploads a new [version](https://developers.cloudflare.com/workers/configuration/versions-and-deployments/#versions) of it to Cloudflare. - `cf-typegen`: Generates a `cloudflare-env.d.ts` file at the root of your project containing [the types for the `env`](https://developers.cloudflare.com/workers/wrangler/commands/#types). -##### 7. Add caching with Cloudflare R2 +##### 7. Add Static Asset Caching + +Add a `public/_headers` file, with at least the following headers: + +```txt +/_next/static/* + Cache-Control: public,max-age=31536000,immutable +``` + +See the [Static Assets Caching docs](/cloudflare/caching#static-assets-caching) for more information. + +##### 8. Add caching with Cloudflare R2 See the [Caching docs](/cloudflare/caching) for information on enabling Next.js caching in your OpenNext project. -##### 8. Remove any `export const runtime = "edge";` if present +##### 9. Remove any `export const runtime = "edge";` if present Before deploying your app, remove the `export const runtime = "edge";` line from any of your source files. The edge runtime is not supported yet with `@opennextjs/cloudflare`. -##### 9. Add `.open-next` to `.gitignore` +##### 10. Add `.open-next` to `.gitignore` You should add `.open-next` to your `.gitignore` file to prevent the build output from being committed to your repository. -##### 10. Remove `@cloudflare/next-on-pages` (if necessary) +##### 11. Remove `@cloudflare/next-on-pages` (if necessary) If your Next.js app currently uses `@cloudflare/next-on-pages`, you'll want to remove it, and make a few changes. @@ -166,7 +177,7 @@ This includes: (those can be replaced with `getCloudflareContext` calls from `@opennextjs/cloudflare`) - next-on-pages eslint rules set in your Eslint config file -##### 11. Develop locally +##### 12. Develop locally You can continue to run `next dev` when developing locally. @@ -194,7 +205,7 @@ After having added the `initOpenNextCloudflareForDev()` call in your Next.js con In step 3, we also added the `npm run preview`, which allows you to quickly preview your app running locally in the Workers runtime, rather than in Node.js. This allows you to test changes in the same runtime as your app will run in when deployed to Cloudflare. -##### 12. Deploy to Cloudflare Workers +##### 13. Deploy to Cloudflare Workers Either deploy via the command line: From 25b1b9885c2432bcbea030f0a23f80960bbce67a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Benjam=C3=ADn=20Vicente?= <62021328+benjavicente@users.noreply.github.com> Date: Sat, 3 May 2025 11:02:56 -0400 Subject: [PATCH 2/5] docs(cloudflare): update static assets callout Co-authored-by: Victor Berchet --- pages/cloudflare/caching.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/cloudflare/caching.mdx b/pages/cloudflare/caching.mdx index cf6f378..883c44a 100644 --- a/pages/cloudflare/caching.mdx +++ b/pages/cloudflare/caching.mdx @@ -215,7 +215,7 @@ For staging, when your site receives low traffic from a single IP, you can repla #### Static Assets Caching - The worker doesn't run **in front** of static assets, so `next.config.js` `headers` option doesn't apply to + The worker doesn't run **in front** of static assets, so the `headers` option of `next.config.ts` doesn't apply to public files (`public`) and static build files (like `_next/static`). From 4320d6d754c4b11c2a0bb77c8d2cd9f669d3d795 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Benjam=C3=ADn=20Vicente?= Date: Sat, 3 May 2025 11:36:54 -0400 Subject: [PATCH 3/5] docs(cloudflare): improve cache explanation --- pages/cloudflare/caching.mdx | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/pages/cloudflare/caching.mdx b/pages/cloudflare/caching.mdx index 883c44a..e08a966 100644 --- a/pages/cloudflare/caching.mdx +++ b/pages/cloudflare/caching.mdx @@ -215,11 +215,13 @@ For staging, when your site receives low traffic from a single IP, you can repla #### Static Assets Caching - The worker doesn't run **in front** of static assets, so the `headers` option of `next.config.ts` doesn't apply to - public files (`public`) and static build files (like `_next/static`). + The worker doesn't run **in front** of static assets, so the `headers` option of `next.config.ts` doesn't + apply to public files (`public`) and static build files (like `_next/static`). -By default, Cloudflare [Static Assets headers](https://developers.cloudflare.com/workers/static-assets/headers/#default-headers) don't enable browser caching. To add browser cache headers or any custom headers to Static Assets, create a `public/_headers` file: +By default, Cloudflare [Static Assets headers](https://developers.cloudflare.com/workers/static-assets/headers/#default-headers) use `max-age=0` with `must-revalidate`, allowing the browser to cache assets but with a revalidation request. This is the [same default behavior as the `public` folder on Next.js](https://nextjs.org/docs/app/api-reference/file-conventions/public-folder#caching). + +Next.js also generates _immutable_ files that don't change between builds. Those files will also be served from Static Assets. To match the [default cache behavior of immutable assets in Next.js](https://nextjs.org/docs/app/guides/self-hosting#automatic-caching), avoiding unnecessary revalidation requests, add the following header to the [`public/_headers`](https://developers.cloudflare.com/workers/static-assets/headers/#custom-headers) file: ```txt /_next/static/* From ba63b8bc60818d83968cbb8c1ca6d1835cc0922a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Benjam=C3=ADn=20Vicente?= Date: Sat, 3 May 2025 11:38:25 -0400 Subject: [PATCH 4/5] docs(cloudflare): static -> immutable --- pages/cloudflare/caching.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/cloudflare/caching.mdx b/pages/cloudflare/caching.mdx index e08a966..1b6c56b 100644 --- a/pages/cloudflare/caching.mdx +++ b/pages/cloudflare/caching.mdx @@ -216,7 +216,7 @@ For staging, when your site receives low traffic from a single IP, you can repla The worker doesn't run **in front** of static assets, so the `headers` option of `next.config.ts` doesn't - apply to public files (`public`) and static build files (like `_next/static`). + apply to public files (`public`) and immutable build files (like `_next/static`). By default, Cloudflare [Static Assets headers](https://developers.cloudflare.com/workers/static-assets/headers/#default-headers) use `max-age=0` with `must-revalidate`, allowing the browser to cache assets but with a revalidation request. This is the [same default behavior as the `public` folder on Next.js](https://nextjs.org/docs/app/api-reference/file-conventions/public-folder#caching). From 4d2e9fe55f67f0f1218b3b46bb28712b5d980443 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Benjam=C3=ADn=20Vicente?= <62021328+benjavicente@users.noreply.github.com> Date: Mon, 5 May 2025 08:51:40 -0400 Subject: [PATCH 5/5] docs(cloudflare): remove note about internal Static Assets usage Co-authored-by: Victor Berchet --- pages/cloudflare/caching.mdx | 2 -- 1 file changed, 2 deletions(-) diff --git a/pages/cloudflare/caching.mdx b/pages/cloudflare/caching.mdx index 1b6c56b..b2f127b 100644 --- a/pages/cloudflare/caching.mdx +++ b/pages/cloudflare/caching.mdx @@ -228,8 +228,6 @@ Next.js also generates _immutable_ files that don't change between builds. Those Cache-Control: public,max-age=31536000,immutable ``` -Internal usage of Static Assets, such as for ISR where assets aren't sent directly to the browser, isn’t affected. - #### Incremental Static Regeneration (ISR) There are 3 storage options for the incremental cache: