From 4ebec400dbef445e1484284722e37df8c706a482 Mon Sep 17 00:00:00 2001 From: Dario Piotrowicz Date: Fri, 24 Jan 2025 22:24:51 +0000 Subject: [PATCH 1/7] cloudflare: add info about `initOpenNextCloudflareForDev` in develop-locally getting-started section --- pages/cloudflare/get-started.mdx | 24 ++++++++++++++++++++++-- 1 file changed, 22 insertions(+), 2 deletions(-) diff --git a/pages/cloudflare/get-started.mdx b/pages/cloudflare/get-started.mdx index b93a4b3..359dda0 100644 --- a/pages/cloudflare/get-started.mdx +++ b/pages/cloudflare/get-started.mdx @@ -172,9 +172,29 @@ This includes: You can continue to run `next dev` when developing locally. -During local development, you can access local versions of Cloudflare bindings as indicated in the [bindings documentation](./bindings). +To do so we recommend you to modify your Next.js configuration file to import and call the `initOpenNextCloudflareForDev` utility +from the `@cloudflare/next-on-pages` package. This makes sure that the Next.js dev server can optimally integrate with the open-next +cloudflare adapter and it is necessary for using bindings during local development. -In step 3, we also added the `npm run preview:worker`, 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. +This is an example of a Next.js configuration file calling the utility: +```js +// next.config.mjs + +import { initOpenNextCloudflareForDev } from "@opennextjs/cloudflare"; + +initOpenNextCloudflareForDev(); + +/** @type {import('next').NextConfig} */ +const nextConfig = {}; + +export default nextConfig; +``` + +After having added the `initOpenNextCloudflareForDev()` call in your Next.js configuration file, you will be able, during local +development, to access in any of your server code, local versions of Cloudflare bindings as indicated in the [bindings documentation](./bindings). + +In step 3, we also added the `npm run preview:worker`, 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 From 4fbbb9107db1846779ab3bfc630f258f97502021 Mon Sep 17 00:00:00 2001 From: Dario Piotrowicz Date: Fri, 24 Jan 2025 22:28:00 +0000 Subject: [PATCH 2/7] update `getCloudflareContext` docs to reflect it being sync now --- pages/cloudflare/bindings.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/pages/cloudflare/bindings.mdx b/pages/cloudflare/bindings.mdx index dfd8aee..48dbbfe 100644 --- a/pages/cloudflare/bindings.mdx +++ b/pages/cloudflare/bindings.mdx @@ -19,7 +19,7 @@ import { getCloudflareContext } from "@opennextjs/cloudflare"; export async function GET(request) { let responseText = "Hello World"; - const myKv = (await getCloudflareContext()).env.MY_KV_NAMESPACE; + const myKv = getCloudflareContext().env.MY_KV_NAMESPACE; await myKv.put("foo", "bar"); const foo = await myKv.get("foo"); @@ -33,7 +33,7 @@ Add bindings to your Worker by adding them to your [wrangler configuration file] ## TypeScript type declarations for bindings -To ensure that the `env` object from `(await getCloudflareContext()).env` above has accurate TypeScript types, run the following Wrangler command to [generate types that match your Worker's configuration](https://developers.cloudflare.com/workers/languages/typescript/#generate-types-that-match-your-workers-configuration-experimental): +To ensure that the `env` object from `getCloudflareContext().env` above has accurate TypeScript types, run the following Wrangler command to [generate types that match your Worker's configuration](https://developers.cloudflare.com/workers/languages/typescript/#generate-types-that-match-your-workers-configuration-experimental): ``` npx wrangler types --experimental-include-runtime @@ -58,7 +58,7 @@ import { getCloudflareContext } from "@opennextjs/cloudflare"; export async function GET(request) { - const { env, cf, ctx } = await getCloudflareContext(); + const { env, cf, ctx } = getCloudflareContext(); // ... } From 962fb8c0610439f7a458464679c9b840268626c4 Mon Sep 17 00:00:00 2001 From: Dario Piotrowicz Date: Fri, 24 Jan 2025 23:41:45 +0000 Subject: [PATCH 3/7] add 0.3 directory and migrate-from-0.3 page --- pages/cloudflare/0.3/_meta.json | 7 + pages/cloudflare/0.3/bindings.mdx | 65 +++++++++ pages/cloudflare/0.3/caching.mdx | 47 +++++++ pages/cloudflare/0.3/examples.mdx | 25 ++++ pages/cloudflare/0.3/get-started.mdx | 187 ++++++++++++++++++++++++++ pages/cloudflare/0.3/index.mdx | 72 ++++++++++ pages/cloudflare/_meta.json | 2 + pages/cloudflare/migrate-from-0.3.mdx | 38 ++++++ 8 files changed, 443 insertions(+) create mode 100644 pages/cloudflare/0.3/_meta.json create mode 100644 pages/cloudflare/0.3/bindings.mdx create mode 100644 pages/cloudflare/0.3/caching.mdx create mode 100644 pages/cloudflare/0.3/examples.mdx create mode 100644 pages/cloudflare/0.3/get-started.mdx create mode 100644 pages/cloudflare/0.3/index.mdx create mode 100644 pages/cloudflare/migrate-from-0.3.mdx diff --git a/pages/cloudflare/0.3/_meta.json b/pages/cloudflare/0.3/_meta.json new file mode 100644 index 0000000..53a20a0 --- /dev/null +++ b/pages/cloudflare/0.3/_meta.json @@ -0,0 +1,7 @@ +{ + "index": "Overview", + "get-started": "", + "bindings": "", + "caching": "", + "examples": "" +} diff --git a/pages/cloudflare/0.3/bindings.mdx b/pages/cloudflare/0.3/bindings.mdx new file mode 100644 index 0000000..ee412f0 --- /dev/null +++ b/pages/cloudflare/0.3/bindings.mdx @@ -0,0 +1,65 @@ +import { SITE } from '../../../config'; +import { Callout } from 'nextra/components'; + +### Bindings + +[Bindings](https://developers.cloudflare.com/workers/runtime-apis/bindings/) allow your Worker to interact with resources on the Cloudflare Developer Platform. When you declare a binding on your Worker, you grant it a specific capability, such as being able to read and write files to an [R2](https://developers.cloudflare.com/r2/) bucket. + +#### How to configure your Next.js app so it can access bindings + +Install [@opennextjs/cloudflare](https://www.npmjs.com/package/@opennextjs/cloudflare), and then add a [wrangler configuration file](https://developers.cloudflare.com/workers/wrangler/configuration/) in the root directory of your Next.js app, as described in [Get Started](/cloudflare/get-started#3-create-a-wranglerjson-file). + +#### How to access bindings in your Next.js app + +You can access [bindings](https://developers.cloudflare.com/workers/runtime-apis/bindings/) from any route of your Next.js app via `getCloudflareContext`: + +```js +import { getCloudflareContext } from "@opennextjs/cloudflare"; + +export async function GET(request) { + let responseText = "Hello World"; + + const myKv = (await getCloudflareContext()).env.MY_KV_NAMESPACE; + await myKv.put("foo", "bar"); + const foo = await myKv.get("foo"); + + return new Response(foo); +} +``` + +#### How to add bindings to your Worker + +Add bindings to your Worker by adding them to your [wrangler configuration file](https://developers.cloudflare.com/workers/wrangler/configuration/). + +## TypeScript type declarations for bindings + +To ensure that the `env` object from `(await getCloudflareContext()).env` above has accurate TypeScript types, run the following Wrangler command to [generate types that match your Worker's configuration](https://developers.cloudflare.com/workers/languages/typescript/#generate-types-that-match-your-workers-configuration-experimental): + +``` +npx wrangler types --experimental-include-runtime +``` + +This will generate a `d.ts` file and (by default) save it to `.wrangler/types/runtime.d.ts`. You will be prompted in the command's output to add that file to your `tsconfig.json`'s `compilerOptions.types` array. + +If you would like to commit the file to git, you can provide a custom path. Here, for instance, the `runtime.d.ts` file will be saved to the root of your project: + +```bash +npx wrangler types --experimental-include-runtime="./runtime.d.ts" +``` + +To ensure that your types are always up-to-date, make sure to run `wrangler types --experimental-include-runtime` after any changes to your config file. + +## Other Cloudflare APIs (`cf`, `ctx`) + +You can access context about the incoming request from the [`cf` object](https://developers.cloudflare.com/workers/runtime-apis/request/#the-cf-property-requestinitcfproperties), as well as lifecycle methods from the [`ctx` object](https://developers.cloudflare.com/workers/runtime-apis/context) from the return value of [`getCloudflareContext()`](https://github.com/opennextjs/opennextjs-cloudflare/blob/main/packages/cloudflare/src/api/get-cloudflare-context.ts): + +```js +import { getCloudflareContext } from "@opennextjs/cloudflare"; + + +export async function GET(request) { + const { env, cf, ctx } = await getCloudflareContext(); + + // ... +} +``` diff --git a/pages/cloudflare/0.3/caching.mdx b/pages/cloudflare/0.3/caching.mdx new file mode 100644 index 0000000..5e4688e --- /dev/null +++ b/pages/cloudflare/0.3/caching.mdx @@ -0,0 +1,47 @@ +import { SITE } from '../../../config'; +import { Callout } from 'nextra/components'; + +## Caching + +`@opennextjs/cloudflare` supports [caching](https://nextjs.org/docs/app/building-your-application/data-fetching/fetching-caching-and-revalidating#caching-data). + +By default, all `fetch()` subrequests made in your Next.js app are cached. Refer to the [Next.js documentation](https://nextjs.org/docs/app/building-your-application/caching#opting-out-1) for information about how to disable caching for an individual subrequest, or for an entire route. + +[The cache persists across deployments](https://nextjs.org/docs/app/building-your-application/caching#data-cache). You are responsible for revalidating/purging this cache. + +Note that [Revalidating](https://nextjs.org/docs/app/building-your-application/data-fetching/fetching-caching-and-revalidating#revalidating-data) is not yet supported. + +Next.js primes the cache at build time. The build time values are serverd by the [Workers Assets](https://developers.cloudflare.com/workers/static-assets/). + + +Workers KV is eventually consistent, which means that it can take up to 60 seconds for updates to be reflected globally, when using the default TTL of 60 seconds. + + +### How to enable caching + +`@opennextjs/cloudflare` uses [Workers KV](https://developers.cloudflare.com/kv/) as the cache for your Next.js app. Workers KV is [fast](https://blog.cloudflare.com/faster-workers-kv) and uses Cloudflare's [Tiered Cache](https://developers.cloudflare.com/cache/how-to/tiered-cache/) to increase cache hit rates. When you write cached data to Workers KV, you write to storage that can be read by any Cloudflare location. This means your app can fetch data, cache it in KV, and then subsequent requests anywhere around the world can read from this cache. + +To enable caching, you must: + +#### 1. Create a KV namespace + +``` +npx wrangler@latest kv namespace create +``` + +#### 2. Add the KV namespace to your Worker + +The binding name used in your app's worker is `NEXT_CACHE_WORKERS_KV`. + +```jsonc +// wrangler.json +{ + // ... + "kv_namespaces": [ + { + "binding": "NEXT_CACHE_WORKERS_KV", + "id": "" + } + ] +} +``` diff --git a/pages/cloudflare/0.3/examples.mdx b/pages/cloudflare/0.3/examples.mdx new file mode 100644 index 0000000..deafb82 --- /dev/null +++ b/pages/cloudflare/0.3/examples.mdx @@ -0,0 +1,25 @@ +import { SITE } from '../../../config'; +import { Callout } from 'nextra/components'; + +## Examples + +To create a new Next.js app, pre-configured to run on Cloudflare using `@opennextjs/cloudflare`, run: + +``` +npm create cloudflare@latest -- my-next-app --framework=next --experimental +``` + +### Basic starter projects + +Basic example apps are included in the repository for `@opennextjs/cloudflare` package: + +- [*`create-next-app`*](https://github.com/opennextjs/opennextjs-cloudflare/tree/main/examples/create-next-app) — a Next.js project bootstrapped with [`create-next-app`](https://nextjs.org/docs/app/api-reference/cli/create-next-app). +- [*`api`*](https://github.com/opennextjs/opennextjs-cloudflare/tree/main/examples/api) — a minimal Next.js project with a single API route +- [*`middleware`*](https://github.com/opennextjs/opennextjs-cloudflare/tree/main/examples/middleware) — a minimal Next.js project using middleware +- [*`vercel-blog-starter`*](https://github.com/opennextjs/opennextjs-cloudflare/tree/main/examples/vercel-blog-starter) — a blog project using SSG + +You can use these to understand how to configure your Next.js app to use `@opennextjs/cloudflare`, or refer to [Get Started](/cloudflare/get-started). + +### Next.js Commerce Demo + +The [Next.js Commerce demo app](https://github.com/vercel/commerce/tree/v1) works with `@opennextjs/cloudflare`. You can view a deployed version of it [here](https://vercel-commerce-on-workers.web-experiments.workers.dev/). diff --git a/pages/cloudflare/0.3/get-started.mdx b/pages/cloudflare/0.3/get-started.mdx new file mode 100644 index 0000000..b3b5668 --- /dev/null +++ b/pages/cloudflare/0.3/get-started.mdx @@ -0,0 +1,187 @@ +import { SITE } from '../../../config'; +import { Callout } from 'nextra/components'; + +### Get Started + +#### New apps + +To create a new Next.js app, pre-configured to run on Cloudflare using `@opennextjs/cloudflare`, run: + +``` +npm create cloudflare@latest -- my-next-app --framework=next --experimental +``` + +#### Existing Next.js apps + +##### 1. Install @opennextjs/cloudflare + +First, install [@opennextjs/cloudflare](https://www.npmjs.com/package/@opennextjs/cloudflare): + +```sh +npm install --save-dev @opennextjs/cloudflare@latest +``` + +##### 2. Install Wrangler + +Install the [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/) as a devDependency: + +```npm +npm install --save-dev wrangler@latest +``` + + +You must use Wrangler version `3.99.0` or later to deploy Next.js apps using `@opennextjs/cloudflare`. + + +##### 3. Create a wrangler configuration file + + +This step is optional since `@opennextjs/cloudflare` creates this file for you during the build process (if not already present). + + +A [wrangler configuration file](https://developers.cloudflare.com/workers/wrangler/configuration/) is needed for your +application to be previewed and deployed, it is also where you configure your Worker and define what resources it can access via [bindings](https://developers.cloudflare.com/workers/runtime-apis/bindings/service-bindings). + +You can create one yourself in the root directory of your Next.js app with the name `wrangler.json` and the following content: +```jsonc +{ + "$schema": "node_modules/wrangler/config-schema.json", + "main": ".open-next/worker.js", + "name": "my-app", + "compatibility_date": "2024-12-30", + "compatibility_flags": ["nodejs_compat"], + "assets": { + "directory": ".open-next/assets", + "binding": "ASSETS", + }, + "kv_namespaces": [ + // Create a KV binding with the binding name "NEXT_CACHE_WORKERS_KV" + // to enable the KV based caching: + // { + // "binding": "NEXT_CACHE_WORKERS_KV", + // "id": "" + // } + ], +} +``` + + +As shown above: + - You must enable the [`nodejs_compat` compatibility flag](https://developers.cloudflare.com/workers/runtime-apis/nodejs/) *and* set your [compatibility date](https://developers.cloudflare.com/workers/configuration/compatibility-dates/) to `2024-09-23` or later, in order for your Next.js app to work with @opennextjs/cloudflare + - The `main` and `assets` values should also not be changed unless you modify the build output result in some way + - You can add a binding named `NEXT_CACHE_WORKERS_KV` to make use of Next.js' caching as described in the [Caching docs](/cloudflare/caching) + + +##### 4. Add an `open-next.config.ts` file + + +This step is optional since `@opennextjs/cloudflare` creates this file for you during the build process (if not already present). + + +Add a [`open-next.config.ts`](https://opennext.js.org/aws/config) file to the root directory of your Next.js app: + +```ts +import type { OpenNextConfig } from "@opennextjs/aws/types/open-next.js"; +import cache from "@opennextjs/cloudflare/kvCache"; + +const config: OpenNextConfig = { + default: { + override: { + wrapper: "cloudflare-node", + converter: "edge", + // set `incrementalCache` to "dummy" to disable KV cache + incrementalCache: async () => cache, + tagCache: "dummy", + queue: "dummy", + }, + }, + + middleware: { + external: true, + override: { + wrapper: "cloudflare-edge", + converter: "edge", + proxyExternalRequest: "fetch", + }, + }, +}; + +export default config; +``` + + +To use the `OpenNextConfig` type as illustrated above (which is not necessary), you need to install the `@opennextjs/aws` NPM package as a dev dependency. + + +##### 5. Add a `.dev.vars` file + +Then, add a [`.dev.vars`](https://developers.cloudflare.com/workers/testing/local-development/#local-only-environment-variables) file to the root directory of your Next.js app: + +```text +NEXTJS_ENV=development +``` + +The `NEXTJS_ENV` variable defines the environment to use when loading Next.js `.env` files. It defaults to "production" when not defined. + +##### 6. Update the `package.json` file + +Add the following to the scripts field of your `package.json` file: + +```json +"build:worker": "opennextjs-cloudflare", +"dev:worker": "wrangler dev --port 8771", +"preview": "npm run build:worker && npm run dev:worker", +"deploy": "npm run build:worker && wrangler deploy", +"cf-typegen": "wrangler types --env-interface CloudflareEnv cloudflare-env.d.ts", +``` + +- `npm run build:worker`: Runs the [@opennextjs/cloudflare](https://www.npmjs.com/package/@opennextjs/cloudflare) adapter. This first builds your app by running the `build` script in your `package.json` (Next.js apps use `next build` by default), and then transforms the build output to a format that you can run locally using [Wrangler](https://developers.cloudflare.com/workers/wrangler/), and deploy to Cloudflare. The build command used by OpenNext can be overridden with the `buildCommand` option in your OpenNext config. +- `npm run dev:worker`: Takes the output generated by `build:worker` and runs it locally in [workerd](https://github.com/cloudflare/workerd), the open-source Workers Runtime, allowing you to run the app locally in the same environment that it will run in production. If you instead run `next dev`, your app will run in Node.js, which is a different JavaScript runtime from the Workers runtime, with differences in behavior and APIs. +- `npm run preview`: Runs `build:worker` and then `dev:worker`, allowing you to quickly preview your app running locally in the Workers runtime, via a single command. +- `npm run deploy`: Builds your app, and then deploys 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 Workers KV + +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 + +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` + +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) + +If your Next.js app currently uses `@cloudflare/next-on-pages`, you'll want to remove it, and make a few changes. + +Uninstalling the [`@cloudflare/next-on-pages`](https://www.npmjs.com/package/@cloudflare/next-on-pages) package as well as the [`eslint-plugin-next-on-pages`](https://www.npmjs.com/package/eslint-plugin-next-on-pages) package if present. + +Remove any reference of these packages from your source and configuration files. +This includes: + - `setupDevPlatform()` calls in your Next.js config file + - `getRequestContext` imports from `@cloudflare/next-on-pages` from your source files + (those can be replaced with `getCloudflareContext` calls from `@opennextjs/cloudflare`) + - next-on-pages eslint rules set in your Eslint config file + +##### 11. Develop locally + +You can continue to run `next dev` when developing locally. + +During local development, you can access local versions of Cloudflare bindings as indicated in the [bindings documentation](./bindings). + +In step 3, we also added the `npm run preview:worker`, 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 + +Either deploy via the command line: + +```sh +npm run deploy:worker +``` + +Or [connect a Github or Gitlab repository](https://developers.cloudflare.com/workers/ci-cd/), and Cloudflare will automatically build and deploy each pull request you merge to your production branch. diff --git a/pages/cloudflare/0.3/index.mdx b/pages/cloudflare/0.3/index.mdx new file mode 100644 index 0000000..3c5e7c3 --- /dev/null +++ b/pages/cloudflare/0.3/index.mdx @@ -0,0 +1,72 @@ +import { SITE } from '../../../config'; +import { Callout } from 'nextra/components'; +import WindowsSupport from '../../../shared/WindowsSupport.mdx'; + +## Cloudflare + +The [`@opennextjs/cloudflare`](https://www.npmjs.com/package/@opennextjs/cloudflare) adapter lets you deploy Next.js apps to [Cloudflare Workers](https://developers.cloudflare.com/workers) using the [Node.js "runtime" from Next.js](https://nextjs.org/docs/app/building-your-application/rendering/edge-and-nodejs-runtimes). + + +[`@opennextjs/cloudflare`](https://www.npmjs.com/package/@opennextjs/cloudflare) is pre 1.0, and still in active development. You should try it, [report bugs](https://github.com/opennextjs/opennextjs-cloudflare/issues), [share feedback](https://github.com/opennextjs/opennextjs-cloudflare/discussions), and contribute code to help make running Next.js apps on Cloudflare easier. We don't quite yet recommend using it for mission-critical production apps. + +You can also use [`@cloudflare/next-on-pages`](https://www.npmjs.com/package/@cloudflare/next-on-pages) to deploy Next.js apps to Cloudflare Pages. You can review the differences in supported Next.js features below and by reviewing [the docs for `@cloudflare/next-on-pages`](https://developers.cloudflare.com/pages/framework-guides/nextjs/ssr/supported-features/), and understand the differences between Workers and Pages [here](https://developers.cloudflare.com/workers/static-assets/compatibility-matrix/). + + + +### Get Started + +##### New apps + +To create a new Next.js app, pre-configured to run on Cloudflare using `@opennextjs/cloudflare`, run: + +``` +npm create cloudflare@latest -- my-next-app --framework=next --experimental +``` + +##### Existing Next.js apps + +Follow the guide [here](/cloudflare/get-started) to use [@opennextjs/cloudflare](https://www.npmjs.com/package/@opennextjs/cloudflare) with an existing Next.js app. + +### Supported Next.js runtimes + +Next.js has [two "runtimes"](https://nextjs.org/docs/app/building-your-application/rendering/edge-and-nodejs-runtimes) — "Edge" and "Node.js". When you use `@opennextjs/cloudflare`, your app should use the Node.js runtime, which is more fully featured, and allows you to use the [Node.js APIs](https://developers.cloudflare.com/workers/runtime-apis/nodejs/) that are provided by the Cloudflare Workers runtime. + +This is an important difference from `@cloudflare/next-on-pages`, which only supports the "Edge" runtime. The Edge Runtime code in Next.js [intentionally constrains which APIs from Node.js can be used](https://github.com/vercel/next.js/blob/canary/packages/next/src/build/webpack/plugins/middleware-plugin.ts#L820), and the "Edge" runtime does not support all Next.js features. + +### Supported Next.js versions + +`@opennextjs/cloudflare` is pre 1.0, and still in active development. We intend to support all minor and patch versions of Next.js 14 and 15. + +To help improve compatibility, we encourage you to [report bugs](https://github.com/opennextjs/opennextjs-cloudflare/issues) and contribute code! + +### Supported Next.js features + +Some Next.js features are not yet supported are not fully tested. +We will update the list as we progress towards releasing 1.0. + +- [x] [App Router](https://nextjs.org/docs/app) +- [x] [Route Handlers](https://nextjs.org/docs/app/building-your-application/routing/route-handlers) +- [x] [Dynamic routes](https://nextjs.org/docs/app/building-your-application/routing/dynamic-routes) +- [x] [Static Site Generation (SSG)](https://nextjs.org/docs/app/building-your-application/rendering/server-components#static-rendering-default) +- [x] [Server-Side Rendering (SSR)](https://nextjs.org/docs/app/building-your-application/rendering/server-components) +- [x] [Middleware](https://nextjs.org/docs/app/building-your-application/routing/middleware) +- [x] [Image optimization](https://nextjs.org/docs/app/building-your-application/optimizing/images) (you can integrate Cloudflare Images with Next.js by following [this guide](https://developers.cloudflare.com/images/transform-images/integrate-with-frameworks/)) +- [ ] [Pages Router](https://nextjs.org/docs/pages) +- [ ] [Incremental Static Regeneration (ISR)](https://nextjs.org/docs/app/building-your-application/data-fetching/incremental-static-regeneration) +- [ ] [Partial Prerendering (PPR)](https://nextjs.org/docs/app/building-your-application/rendering/partial-prerendering) +- [ ] [Support for after](https://nextjs.org/blog/next-15-rc#executing-code-after-a-response-with-nextafter-experimental) +- [ ] [Composable Caching](https://nextjs.org/blog/composable-caching) (`'use cache'`) is a Next.js 15 feature and not supported yet. + +We welcome both contributions and feedback! + +### Windows support + + + +### How `@opennextjs/cloudflare` Works + +The OpenNext Cloudflare adapter works by taking the Next.js build output and transforming it, so that it can run in Cloudflare Workers. + +When you add [@opennextjs/cloudflare](https://www.npmjs.com/package/@opennextjs/cloudflare) as a dependency to your Next.js app, and then run `npx opennextjs-cloudflare` the adapter first builds your app by running the `build` script in your `package.json`, and then transforms the build output to a format that you can run locally using [Wrangler](https://developers.cloudflare.com/workers/wrangler/), and deploy to Cloudflare. + +You can view the code for `@opennextjs/cloudflare` [here](https://github.com/opennextjs/opennextjs-cloudflare/blob/main/packages/cloudflare/src) to understand what it does under the hood. diff --git a/pages/cloudflare/_meta.json b/pages/cloudflare/_meta.json index 8d0c8fa..8fa034a 100644 --- a/pages/cloudflare/_meta.json +++ b/pages/cloudflare/_meta.json @@ -5,6 +5,8 @@ "caching": "", "examples": "", "troubleshooting": "", + "migrate-from-0.3": "", + "0.3": "Release 0.3", "migrate-from-0.2": "", "0.2": "Release 0.2" } diff --git a/pages/cloudflare/migrate-from-0.3.mdx b/pages/cloudflare/migrate-from-0.3.mdx new file mode 100644 index 0000000..5ca98ba --- /dev/null +++ b/pages/cloudflare/migrate-from-0.3.mdx @@ -0,0 +1,38 @@ +import { SITE } from '../../config'; +import { Callout } from 'nextra/components'; + +### Migrate from 0.3 + +The `@opennextjs/cloudflare@0.4.0` introduced a new `initOpenNextCloudflareForDev` utility and made `getCloudflareContext` synchronous, +we'll explore those two differences below, and how they effect applications built using `0.3.x` versions of the adapter. + +##### `initOpenNextCloudflareForDev` + +`initOpenNextCloudflareForDev` is a new utility that needs to be added to the Next.js configuration file in order to integrate the adapter +with the Next.js dev server. If you don't plan on using the `next dev` command you can skip this section, otherwise update your Next.js +configuration file to import and call the utility. + +Example: +```js +// next.config.mjs + +import { initOpenNextCloudflareForDev } from "@opennextjs/cloudflare"; + +initOpenNextCloudflareForDev(); + +/** @type {import('next').NextConfig} */ +const nextConfig = {}; + +export default nextConfig; +``` + +##### Synchronous `getCloudflareContext` synchronous + +`getCloudflareContext` has been changed not to synchronously return the Cloudflare context object instead or returning +a promise that resolves to it. + +This means that if you had code that `await`ed `getCloudflareContext()` calls, such `await`s are no longer necessary and +can be removed. + +If your application is instead combining the result of `getCloudflareContext()` with on Ecmascript Promises APIs such as +`then`, `catch` and `finally` those need to be removed since the function's result, as mentioned is no longer a promise. From 944abd273e8b7716ba623bcb3401057047afdd50 Mon Sep 17 00:00:00 2001 From: Dario Piotrowicz Date: Sat, 25 Jan 2025 00:04:23 +0000 Subject: [PATCH 4/7] update migrate-from-0.2 page --- pages/cloudflare/migrate-from-0.2.mdx | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/pages/cloudflare/migrate-from-0.2.mdx b/pages/cloudflare/migrate-from-0.2.mdx index aaf01b0..d122265 100644 --- a/pages/cloudflare/migrate-from-0.2.mdx +++ b/pages/cloudflare/migrate-from-0.2.mdx @@ -80,4 +80,9 @@ The name of the CLI was changed to `opennextjs-cloudflare`: ##### 5 Add `.open-next` to `.gitignore` You should change `.worker-next` to `.open-next` in your `.gitignore` file to prevent the build output from being committed to your repository. -You can safely delete the content of the now unused `.worker-next`. \ No newline at end of file +You can safely delete the content of the now unused `.worker-next`. + +##### 6. Apply 0.3.x updates + +Finally to complete the migration you need to import and call the `initOpenNextCloudflareForDev` utility in your Next.js configuration file +and convert potential `getCloudflareContext()` call, for more details see the [migrate-from-0.3 documentation](./migrate-from-0.3.mdx). From 43fb44e2ec374b9dc2b0e3d356ae470fb2f6b460 Mon Sep 17 00:00:00 2001 From: Dario Piotrowicz Date: Mon, 27 Jan 2025 10:42:22 +0000 Subject: [PATCH 5/7] change migrate-from-0.2 page to migrate-from-0.2-to-0.3 --- pages/cloudflare/_meta.json | 2 +- .../{migrate-from-0.2.mdx => migrate-from-0.2-to-0.3.mdx} | 7 +------ 2 files changed, 2 insertions(+), 7 deletions(-) rename pages/cloudflare/{migrate-from-0.2.mdx => migrate-from-0.2-to-0.3.mdx} (88%) diff --git a/pages/cloudflare/_meta.json b/pages/cloudflare/_meta.json index 8fa034a..4134899 100644 --- a/pages/cloudflare/_meta.json +++ b/pages/cloudflare/_meta.json @@ -7,6 +7,6 @@ "troubleshooting": "", "migrate-from-0.3": "", "0.3": "Release 0.3", - "migrate-from-0.2": "", + "migrate-from-0.2-to-0.3": "", "0.2": "Release 0.2" } diff --git a/pages/cloudflare/migrate-from-0.2.mdx b/pages/cloudflare/migrate-from-0.2-to-0.3.mdx similarity index 88% rename from pages/cloudflare/migrate-from-0.2.mdx rename to pages/cloudflare/migrate-from-0.2-to-0.3.mdx index d122265..68160a6 100644 --- a/pages/cloudflare/migrate-from-0.2.mdx +++ b/pages/cloudflare/migrate-from-0.2-to-0.3.mdx @@ -1,7 +1,7 @@ import { SITE } from '../../config'; import { Callout } from 'nextra/components'; -### Migrate from 0.2 +### Migrate from 0.2 to 0.3 The `@opennextjs/cloudflare` adapter is now more closely intgrated with `@opennextjs/aws`. @@ -81,8 +81,3 @@ The name of the CLI was changed to `opennextjs-cloudflare`: You should change `.worker-next` to `.open-next` in your `.gitignore` file to prevent the build output from being committed to your repository. You can safely delete the content of the now unused `.worker-next`. - -##### 6. Apply 0.3.x updates - -Finally to complete the migration you need to import and call the `initOpenNextCloudflareForDev` utility in your Next.js configuration file -and convert potential `getCloudflareContext()` call, for more details see the [migrate-from-0.3 documentation](./migrate-from-0.3.mdx). From f8f924081fe3eb33f00cbf588fe34a41de3f9489 Mon Sep 17 00:00:00 2001 From: Dario Piotrowicz Date: Mon, 27 Jan 2025 10:44:17 +0000 Subject: [PATCH 6/7] Apply suggestions from code review Co-authored-by: Victor Berchet --- pages/cloudflare/get-started.mdx | 2 +- pages/cloudflare/migrate-from-0.3.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/pages/cloudflare/get-started.mdx b/pages/cloudflare/get-started.mdx index 359dda0..c35d63c 100644 --- a/pages/cloudflare/get-started.mdx +++ b/pages/cloudflare/get-started.mdx @@ -172,7 +172,7 @@ This includes: You can continue to run `next dev` when developing locally. -To do so we recommend you to modify your Next.js configuration file to import and call the `initOpenNextCloudflareForDev` utility +Modify your Next.js configuration file to import and call the `initOpenNextCloudflareForDev` utility from the `@cloudflare/next-on-pages` package. This makes sure that the Next.js dev server can optimally integrate with the open-next cloudflare adapter and it is necessary for using bindings during local development. diff --git a/pages/cloudflare/migrate-from-0.3.mdx b/pages/cloudflare/migrate-from-0.3.mdx index 5ca98ba..bdd623b 100644 --- a/pages/cloudflare/migrate-from-0.3.mdx +++ b/pages/cloudflare/migrate-from-0.3.mdx @@ -28,7 +28,7 @@ export default nextConfig; ##### Synchronous `getCloudflareContext` synchronous -`getCloudflareContext` has been changed not to synchronously return the Cloudflare context object instead or returning +`getCloudflareContext` is now synchronous. a promise that resolves to it. This means that if you had code that `await`ed `getCloudflareContext()` calls, such `await`s are no longer necessary and From 9c0a227425e94fcbe0bcc594c8a5a32c35a709cc Mon Sep 17 00:00:00 2001 From: Dario Piotrowicz Date: Mon, 27 Jan 2025 18:02:01 +0000 Subject: [PATCH 7/7] rename file --- pages/cloudflare/_meta.json | 2 +- .../{migrate-from-0.3.mdx => migrate-from-0.3-to-0.4.mdx} | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) rename pages/cloudflare/{migrate-from-0.3.mdx => migrate-from-0.3-to-0.4.mdx} (97%) diff --git a/pages/cloudflare/_meta.json b/pages/cloudflare/_meta.json index 4134899..4bad224 100644 --- a/pages/cloudflare/_meta.json +++ b/pages/cloudflare/_meta.json @@ -5,7 +5,7 @@ "caching": "", "examples": "", "troubleshooting": "", - "migrate-from-0.3": "", + "migrate-from-0.3-to-0.4": "Migrate from 0.3", "0.3": "Release 0.3", "migrate-from-0.2-to-0.3": "", "0.2": "Release 0.2" diff --git a/pages/cloudflare/migrate-from-0.3.mdx b/pages/cloudflare/migrate-from-0.3-to-0.4.mdx similarity index 97% rename from pages/cloudflare/migrate-from-0.3.mdx rename to pages/cloudflare/migrate-from-0.3-to-0.4.mdx index bdd623b..81c9df5 100644 --- a/pages/cloudflare/migrate-from-0.3.mdx +++ b/pages/cloudflare/migrate-from-0.3-to-0.4.mdx @@ -1,7 +1,7 @@ import { SITE } from '../../config'; import { Callout } from 'nextra/components'; -### Migrate from 0.3 +### Migrate from 0.3 (to 0.4) The `@opennextjs/cloudflare@0.4.0` introduced a new `initOpenNextCloudflareForDev` utility and made `getCloudflareContext` synchronous, we'll explore those two differences below, and how they effect applications built using `0.3.x` versions of the adapter.