opennextjs · irvinebroque · Sep 26, 2024 · Sep 24, 2024 · Sep 24, 2024 · Sep 24, 2024
@@ -13,7 +13,7 @@ If you're migrating from V2 to V3, you can find the migration guide [here](/migr
 ---
 
 OpenNext takes the Next.js build output and converts it into packages that can be deployed across a variety of environments.
-Natively OpenNext has support for AWS Lambda and classic Node Server. It also offer partial support for the `edge` runtime in Cloudflare Workers.
+Natively OpenNext has support for AWS Lambda, [Cloudflare](/cloudflare), and classic Node.js Server.
 
 One notable feature of OpenNext is its ability to split the Next.js output, enabling selective deployment to different targets such as AWS Lambda, Cloudflare Workers, or Amazon ECS. This facilitates a tailored deployment strategy that aligns with the specific needs of your application.
 

@@ -0,0 +1,85 @@
+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.
+
+<Callout>
+If your app uses both bindings and @opennextjs/cloudflare, you currently cannot access bindings when running `next dev`. Instead, you must build your app using @opennextjs/cloudflare and then run it locally in the Workers runtime as described [here](/cloudflare/get-started). This means you cannot use hot-module reloading (HMR) for a faster development workflow. @opennextjs/cloudflare is pre 1.0, in active development, and we plan to address this soon.
+
+Alternatively, you can 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 between @opennextjs/cloudflare and @cloudflare/next-on-pages [here](LINK).
+</Callout>
+
+#### 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.toml` file in the root directory of your Next.js app, as described in [Get Started](/cloudflare/get-started), y
+
+#### 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 `getRequestContext`:
+
+```js
+// TODO: possible to bring this in from next-on-pages?
+import { getRequestContext } from "@cloudflare/next-on-pages";
+
+export async function GET(request) {
+	let responseText = "Hello World";
+
+	const myKv = getRequestContext().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.toml` configuration file](/pages/functions/wrangler-configuration/).
+
+## TypeScript type declarations for bindings
+
+To ensure that the `env` object from `getRequestContext().env` above has accurate TypeScript types, install [`@cloudflare/workers-types`](https://www.npmjs.com/package/@cloudflare/workers-types) and create a [TypeScript declaration file](https://www.typescriptlang.org/docs/handbook/2/type-declarations.html).
+
+Install Workers Types:
+
+```sh
+npm install --save-dev @cloudflare/workers-types
+```
+
+Add Workers Types to your `tsconfig.json` file, replacing the date below with your project's [compatibility date](https://developers.cloudflare.com/workers/configuration/compatibility-dates/):
+
+```diff title="tsconfig.json"
+    "types": [
++        "@cloudflare/workers-types/2024-07-29"
+    ]
+```
+
+Create an `env.d.ts` file in the root directory of your Next.js app, and explicitly declare the type of each binding:
+
+```ts title="env.d.ts"
+interface CloudflareEnv {
+	MY_KV_1: KVNamespace;
+	MY_KV_2: KVNamespace;
+	MY_R2: R2Bucket;
+	MY_DO: DurableObjectNamespace;
+}
+```
+
+## 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/#incomingrequestcfproperties), as well as [lifecycle methods from the `ctx` object](https://developers.cloudflare.com/workers/runtime-apis/handlers/fetch/#lifecycle-methods) from the return value of [`getRequestContext()`](https://github.com/cloudflare/next-on-pages/blob/main/packages/next-on-pages/src/api/getRequestContext.ts):
+
+```js
+// TODO: possible to bring this in from next-on-pages?
+import { getRequestContext } from "@cloudflare/next-on-pages";
+
+export const runtime = "edge";
+
+export async function GET(request) {
+	const { env, cf, ctx } = getRequestContext();
+
+	// ...
+}
+```
@@ -0,0 +1,6 @@
+import { SITE } from '../../config';
+import { Callout } from 'nextra/components';
+
+## Caching
+
+TODO
@@ -0,0 +1,19 @@
+import { SITE } from '../../config';
+import { Callout } from 'nextra/components';
+
+## Examples
+
+### Basic starter projects
+
+Two 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
+
+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](TODO).
+
+To run this using `@opennextjs/cloudflare`, TODO.
@@ -0,0 +1,66 @@
+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:
+
+```
+<command>
+```
+
+#### Existing Next.js apps
+
+##### 1. Install @cloudflare/next-on-pages
+
+First, install [@opennextjs/cloudflare](https://www.npmjs.com/package/@opennextjs/cloudflare):
+
+```sh
+npm install --save-dev @opennextjs/cloudflare
+```
+
+##### 2. Add a `wrangler.toml` file
+
+Then, add a [`wrangler.toml`](https://developers.cloudflare.com/workers/wrangler/configuration/) file to the root directory of your Next.js app:
+
+```toml
+main = ".worker-next/index.mjs"
+name = "my-app"
+compatibility_date = "2024-09-23"
+compatibility_flags = ["nodejs_compat"]
+experimental_assets = { directory = ".worker-next/assets", binding = "ASSETS" }
+```
+
+<Callout>
+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.
+</Callout>
+
+`wrangler.toml` is where you configure your Worker and define what resources it can access via [bindings](/workers/runtime-apis/bindings/).
+
+##### 3. Update `package.json`
+
+Add the following to the scripts field of your `package.json` file:
+
+```json title="package.json"
+"build:worker": "cloudflare", TODO
+"dev:worker": "wrangler dev --port 8771",
+"preview:worker": "npm run build:worker && npm run dev:worker",
+"deploy:worker": "npm run build:worker && wrangler deploy"
+```
+
+- `npm run build:worker`: Runs the [@opennextjs/cloudflare](https://www.npmjs.com/package/@opennextjs/cloudflare) adapter. This first builds your app by running `next build` behind the scenes, 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.
+- `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:worker`: Runs `build:worker` and then `preview: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
+
+##### 4. Deploy to Cloudflare Workers
+
+Either deploy via the command line:
+
+```sh
+npm run deploy
+```
+
+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.
@@ -1,2 +1,57 @@
-### TODO
+import { SITE } from '../../config';
+import { Callout } from 'nextra/components';
 
+## 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) and [Cloudflare Pages](https://developers.cloudflare.com/pages), using the [Node.js "runtime" from Next.js](https://nextjs.org/docs/app/building-your-application/rendering/edge-and-nodejs-runtimes).
+
+<Callout>
+[@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), and [share feedback](https://github.com/opennextjs/opennextjs-cloudflare/discussions) 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 between @opennextjs/cloudflare and @cloudflare/next-on-pages [here](LINK).
+</Callout>
+
+### Get Started
+
+##### New apps
+
+To create a new Next.js app, pre-configured to run on Cloudflare using @opennextjs/cloudflare, run:
+
+```
+<command>
+```
+
+##### 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 can use the Node.js runtime, which is more fully featured, and allows you to use the [Node.js APIs](/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 features
+
+- [x] [App Router](https://nextjs.org/docs/app) & [Pages Router](https://nextjs.org/docs/pages)
+- [x] [API routes](https://nextjs.org/docs/pages/building-your-application/routing/api-routes)
+- [x] [Dynamic routes](https://nextjs.org/docs/pages/building-your-application/routing/dynamic-routes)
+- [x] [Static Site Generation (SSG)](https://nextjs.org/docs/pages/building-your-application/rendering/static-site-generation)
+- [x] [Server-Side Rendering (SSR)](https://nextjs.org/docs/pages/building-your-application/rendering/server-side-rendering)
+- [x] [Incremental Static Regeneration (ISR)](https://nextjs.org/docs/pages/building-your-application/data-fetching/incremental-static-regeneration)
+
+### Not Yet Supported Next.js features
+
+- [ ] [Partial Prerendering (PPR)](https://nextjs.org/docs/app/building-your-application/rendering/partial-prerendering)
+- [ ] [Middleware](https://nextjs.org/docs/app/building-your-application/routing/middleware)
+- [ ] [Image optimization](https://nextjs.org/docs/pages/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/))
+- [ ] [NextAuth.js](https://next-auth.js.org)
+- [ ] [Experimental streaming support](https://nextjs.org/blog/next-15-rc#executing-code-after-a-response-with-nextafter-experimental)
+
+### 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 `pnpx cloudflare` (TODO: why pnpx?), the adapter first builds your app by running `next build`, 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/index.mdx b/pages/index.mdx
@@ -2,7 +2,7 @@ import { SITE } from '../config';
 
 # OpenNext
 
-Next.js, unlike Remix, Astro, or the other modern frontends, doesn't have a way to self-host across different platforms. You can run it as a Node application. But this doesn't work the same way as it does on Vercel.
+Next.js, unlike Remix, Astro, or the other modern frontends, doesn't have a way to self-host across different platforms. You can run it as a Node.js application. But this doesn't work the same way as it does on Vercel.
 
 ---
 
@@ -14,10 +14,10 @@ OpenNext is an initiative to bring all these efforts together.
 
 ---
 
-OpenNext is currently backed by.
+OpenNext is currently backed by:
 
 1. [SST](https://sst.dev) community, maintains the [AWS](aws) adapter
-2. [Cloudflare](https://www.cloudflare.com) team, maintains the [Cloudflare](cloudflare) adapter
+2. [Cloudflare](https://developers.cloudflare.com/) team, maintains the [Cloudflare](cloudflare) adapter
 3. [Netlify](http://netlify.com) team, maintains the [Netlify](netlify) adapter
 
 If you'd like to join the effort, connect with us on [Discord](https://discord.gg/opennextjs).