|
| 1 | +import { SITE } from '../../config'; |
| 2 | +import { Callout } from 'nextra/components'; |
| 3 | + |
| 4 | +### Bindings |
| 5 | + |
| 6 | +[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. |
| 7 | + |
| 8 | +<Callout> |
| 9 | +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. |
| 10 | + |
| 11 | +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). |
| 12 | +</Callout> |
| 13 | + |
| 14 | +#### How to configure your Next.js app so it can access bindings |
| 15 | + |
| 16 | +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 |
| 17 | + |
| 18 | +#### How to access bindings in your Next.js app |
| 19 | + |
| 20 | +You can access [bindings](https://developers.cloudflare.com/workers/runtime-apis/bindings/) from any route of your Next.js app via `getRequestContext`: |
| 21 | + |
| 22 | +```js |
| 23 | +// TODO: possible to bring this in from next-on-pages? |
| 24 | +import { getRequestContext } from "@cloudflare/next-on-pages"; |
| 25 | + |
| 26 | +export async function GET(request) { |
| 27 | + let responseText = "Hello World"; |
| 28 | + |
| 29 | + const myKv = getRequestContext().env.MY_KV_NAMESPACE; |
| 30 | + await myKv.put("foo", "bar"); |
| 31 | + const foo = await myKv.get("foo"); |
| 32 | + |
| 33 | + return new Response(foo); |
| 34 | +} |
| 35 | +``` |
| 36 | + |
| 37 | +#### How to add bindings to your Worker |
| 38 | + |
| 39 | +Add bindings to your Worker by [adding them to your `wrangler.toml` configuration file](/pages/functions/wrangler-configuration/). |
| 40 | + |
| 41 | +## TypeScript type declarations for bindings |
| 42 | + |
| 43 | +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). |
| 44 | + |
| 45 | +Install Workers Types: |
| 46 | + |
| 47 | +```sh |
| 48 | +npm install --save-dev @cloudflare/workers-types |
| 49 | +``` |
| 50 | + |
| 51 | +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/): |
| 52 | + |
| 53 | +```diff title="tsconfig.json" |
| 54 | + "types": [ |
| 55 | ++ "@cloudflare/workers-types/2024-07-29" |
| 56 | + ] |
| 57 | +``` |
| 58 | + |
| 59 | +Create an `env.d.ts` file in the root directory of your Next.js app, and explicitly declare the type of each binding: |
| 60 | + |
| 61 | +```ts title="env.d.ts" |
| 62 | +interface CloudflareEnv { |
| 63 | + MY_KV_1: KVNamespace; |
| 64 | + MY_KV_2: KVNamespace; |
| 65 | + MY_R2: R2Bucket; |
| 66 | + MY_DO: DurableObjectNamespace; |
| 67 | +} |
| 68 | +``` |
| 69 | + |
| 70 | +## Other Cloudflare APIs (`cf`, `ctx`) |
| 71 | + |
| 72 | +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): |
| 73 | + |
| 74 | +```js |
| 75 | +// TODO: possible to bring this in from next-on-pages? |
| 76 | +import { getRequestContext } from "@cloudflare/next-on-pages"; |
| 77 | + |
| 78 | +export const runtime = "edge"; |
| 79 | + |
| 80 | +export async function GET(request) { |
| 81 | + const { env, cf, ctx } = getRequestContext(); |
| 82 | + |
| 83 | + // ... |
| 84 | +} |
| 85 | +``` |
0 commit comments