Skip to content

update and improve the Cloudflare adapter getting started guide #45

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Jan 7, 2025
Merged

update and improve the Cloudflare adapter getting started guide #45

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
96b771d
update and improve the Cloudflare adapter getting started guide
dario-piotrowicz Jan 2, 2025
e91feb9
add missing `.js` extension to `@opennextjs/aws/types/open-next` imports
dario-piotrowicz Jan 7, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
125 changes: 61 additions & 64 deletions pages/cloudflare/get-started.mdx
View file
Open in desktop
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
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've added @latest to be consistent with wrangler below (I'm just making this change for consistency, I don't have a strong preference here, we can or not have @latest, whatever you prefer)

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
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've updated -D to --save-dev to be consistent with @opennextjs/cloudflare above (I'm just making this change for consistency, I don't have a strong preference here, we can go with either version)

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`
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm trying to clean things up a bit here

We have both a Remove '@cloudflare/next-on-pages' (if necessary) and a Uninstall '@cloudflare/next-on-pages' section, this seems pretty confusing to me, also the hierarchy is a bit out of whack I think (for example, Add '.open-next' to '.gitignore' is under Remove '@cloudflare/next-on-pages' (if necessary), that doesn't seem correct to me)


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",
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

these are the scripts the C3 generates for users, but people can create their apps manually and not via C3 or update the name of such scripts, so I think that maybe it makes sense to just be generic here and say to remove any reference to the next-on-pages package and be done with it

- "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
Open in desktop
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
Loading