Skip to content

Commit

Permalink
update and improve the Cloudflare adapter getting started guide (#45)
Browse files Browse the repository at this point in the history
  • Loading branch information
@dario-piotrowicz
dario-piotrowicz authored Jan 7, 2025
1 parent 1ed0733 commit 2beac6f
Show file tree
Hide file tree
Showing 2 changed files with 62 additions and 65 deletions.
125 changes: 61 additions & 64 deletions pages/cloudflare/get-started.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,54 +23,77 @@ Use the template from `flarelabs-net/workers-next` as indicated above to use 0.3
First, install [@opennextjs/cloudflare](https://www.npmjs.com/package/@opennextjs/cloudflare):

```sh
npm install --save-dev @opennextjs/cloudflare
npm install --save-dev @opennextjs/cloudflare@latest
```

##### 2. Install Wrangler, and add a `wrangler.toml` file
##### 2. Install Wrangler

Install the [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/) as a devDependency:

```npm
npm install -D wrangler@latest
npm install --save-dev wrangler@latest
```

<Callout>
You must use Wrangler version `3.99.0` or later to deploy Next.js apps using `@opennextjs/cloudflare`.
</Callout>

Then, add a [`wrangler.toml`](https://developers.cloudflare.com/workers/wrangler/configuration/) file to the root directory of your Next.js app:
##### 3. Create a `wrangler.json` file

```toml
main = ".open-next/worker.js"
name = "my-app"

compatibility_date = "2024-09-23"
compatibility_flags = ["nodejs_compat"]
<Callout type='info'>
This step is optional since `@opennextjs/cloudflare` creates this file for you during the build process (if not already present).
</Callout>

# The binding name must be "ASSETS" when the cache is enabled
assets = { directory = ".open-next/assets", binding = "ASSETS" }
A [`wrangler.json`](https://developers.cloudflare.com/workers/wrangler/configuration/) file 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 with the following content:
```jsonc
{
"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": "<BINDING_ID>"
// }
],
}
```

<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.
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)
</Callout>

`wrangler.toml` is where you configure your Worker and define what resources it can access via [bindings](https://developers.cloudflare.com/workers/runtime-apis/bindings/service-bindings).
##### 4. Add an `open-next.config.ts` file

##### 3. Add a `open-next.config.ts` file
<Callout type='info'>
This step is optional since `@opennextjs/cloudflare` creates this file for you during the build process (if not already present).
</Callout>

Then, add a [`open-next.config.ts`](https://opennext.js.org/aws/config) file to the root directory of your Next.js app:
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";
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
// set `incrementalCache` to "dummy" to disable KV cache
incrementalCache: async () => cache,
tagCache: "dummy",
queue: "dummy",
Expand All @@ -90,9 +113,11 @@ const config: OpenNextConfig = {
export default config;
```

You can either install the `@opennextjs/aws` NPM package to get the types or `open-next.config.ts` to the [`exclude`](https://www.typescriptlang.org/tsconfig/#exclude) configuration key of your `tsconfig.json`.
<Callout>
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.
</Callout>

##### 4. Add a `.dev.vars` file
##### 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:

Expand All @@ -102,7 +127,7 @@ 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.

##### 5. Update `package.json`
##### 6. Update the `package.json` file

Add the following to the scripts field of your `package.json` file:

Expand All @@ -118,70 +143,42 @@ Add the following to the scripts field of your `package.json` file:
- `npm run preview:worker`: 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

### 6. Add caching with Workers KV
##### 7. Add caching with Workers KV

See the [Caching docs](/cloudflare/caching) for information on enabling Next.js caching in your OpenNext project.

### 7. 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.
##### 8. Remove any `export const runtime = "edge";` if present

#### Remove `export const runtime = "edge";`
Before deploying your app, remove the `export const runtime = "edge";` line from any of your source files.

Before deploying your app, remove the `export const runtime = "edge";` line from your `next.config.js` file.
The edge runtime is not supported yet with `@opennextjs/cloudflare`.

#### Add `.open-next` to `.gitignore`
##### 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.

#### Uninstall `@cloudflare/next-on-pages`

You should uninstall `@cloudflare/next-on-pages` and remove any references to it.

In `package.json`:
##### 10. Remove `@cloudflare/next-on-pages` (if necessary)

```diff
"scripts": {
- "pages:build": "npx @cloudflare/next-on-pages",
- "preview": "npm run pages:build && wrangler pages dev",
- "deploy": "npm run pages:build && wrangler pages deploy"

"devDependencies": {
- "@cloudflare/next-on-pages": "*",
```

(remember to also remove [eslint-plugin-next-on-pages](https://www.npmjs.com/package/eslint-plugin-next-on-pages) from your `.eslintrc.js` file)

You no longer need to call `setupDevPlatform()` in your `next.config.mjs` file:

```diff title="next.config.mjs"
- import { setupDevPlatform } from '@cloudflare/next-on-pages/next-dev';

/** @type {import('next').NextConfig} */
const nextConfig = {};

- if (process.env.NODE_ENV === 'development') {
- await setupDevPlatform();
- }
```
If your Next.js app currently uses `@cloudflare/next-on-pages`, you'll want to remove it, and make a few changes.

And you'll want to replace any uses of `getRequestContext` from `@cloudflare/next-on-pages` with `getCloudflareContext` from `@opennextjs/cloudflare`:
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.

```diff
- import { getRequestContext } from "@cloudflare/next-on-pages";
+ import { getCloudflareContext } from "@opennextjs/cloudflare";
```
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

##### 8. Develop locally
##### 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.

##### 9. Deploy to Cloudflare Workers
##### 12. Deploy to Cloudflare Workers

Either deploy via the command line:

Expand Down
2 changes: 1 addition & 1 deletion pages/cloudflare/migrate-from-0.2.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ assets = { directory = ".open-next/assets", binding = "ASSETS" }
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";
import type { OpenNextConfig } from "@opennextjs/aws/types/open-next.js";
import cache from "@opennextjs/cloudflare/kvCache";

const config: OpenNextConfig = {
Expand Down

0 comments on commit 2beac6f

Please sign in to comment.