update and improve the Cloudflare adapter getting started guide (#45)

Author: dario-piotrowicz

pages/cloudflare/get-started.mdx

@@ -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",
@@ -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:
 
@@ -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:
 
@@ -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:
 

pages/cloudflare/migrate-from-0.2.mdx

@@ -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 = {