From f7c5f6c7207c686ae3cc87635aaf893b10018e9b Mon Sep 17 00:00:00 2001 From: Akihiro Nagai <77012577+314systems@users.noreply.github.com> Date: Mon, 27 Apr 2026 20:57:36 +0900 Subject: [PATCH 1/6] docs: normalize code blocks and add filename attributes --- pages/aws/common_issues.mdx | 22 +++---- pages/aws/config.mdx | 4 +- pages/aws/config/custom_overrides.mdx | 47 ++++++--------- pages/aws/config/full_example.mdx | 2 +- pages/aws/config/nx.mdx | 10 ++-- pages/aws/config/reference.mdx | 2 +- pages/aws/config/simple_example.mdx | 14 ++--- pages/aws/contribute.mdx | 6 +- pages/aws/contribute/local_run.mdx | 5 +- pages/aws/contribute/plugin.mdx | 6 +- pages/aws/get_started.mdx | 2 +- pages/aws/inner_workings.mdx | 2 +- pages/aws/inner_workings/architecture.mdx | 8 +-- .../aws/inner_workings/cache_interception.mdx | 3 +- pages/aws/inner_workings/caching.mdx | 3 +- .../components/image_optimization.mdx | 2 +- .../inner_workings/components/initializer.mdx | 2 +- .../inner_workings/components/middleware.mdx | 6 +- .../inner_workings/components/overview.mdx | 6 +- .../components/revalidation.mdx | 2 +- .../inner_workings/components/server/node.mdx | 2 +- .../aws/inner_workings/components/warmer.mdx | 4 +- pages/aws/inner_workings/routing.mdx | 4 +- pages/aws/migration.mdx | 2 +- pages/aws/v2/advanced/architecture.mdx | 8 +-- pages/aws/v2/advanced/debugging.mdx | 2 +- pages/aws/v2/advanced/options.mdx | 30 ++++------ pages/aws/v2/advanced/workaround.mdx | 18 +++--- pages/aws/v2/common_issues/bundle_size.mdx | 2 +- pages/aws/v2/common_issues/isr.mdx | 3 +- pages/aws/v2/inner_workings/isr.mdx | 10 ++-- pages/aws/v2/inner_workings/plugin.mdx | 2 +- pages/aws/v2/inner_workings/streaming.mdx | 2 +- pages/aws/v2/inner_workings/warming.mdx | 8 +-- pages/cloudflare/bindings.mdx | 4 +- pages/cloudflare/caching.mdx | 58 ++++++++----------- pages/cloudflare/examples.mdx | 2 +- .../former-releases/0.2/bindings.mdx | 4 +- .../former-releases/0.2/caching.mdx | 4 +- .../former-releases/0.2/examples.mdx | 2 +- .../former-releases/0.2/get-started.mdx | 12 ++-- .../cloudflare/former-releases/0.2/index.mdx | 2 +- .../former-releases/0.3/bindings.mdx | 4 +- .../former-releases/0.3/caching.mdx | 5 +- .../former-releases/0.3/examples.mdx | 2 +- .../former-releases/0.3/get-started.mdx | 14 ++--- .../cloudflare/former-releases/0.3/index.mdx | 2 +- .../former-releases/0.5/bindings.mdx | 4 +- .../former-releases/0.5/caching.mdx | 14 ++--- .../former-releases/0.5/examples.mdx | 2 +- .../former-releases/0.5/get-started.mdx | 11 ++-- .../cloudflare/former-releases/0.5/index.mdx | 2 +- .../former-releases/0.6/bindings.mdx | 4 +- .../former-releases/0.6/caching.mdx | 39 +++++-------- .../former-releases/0.6/examples.mdx | 2 +- .../former-releases/0.6/get-started.mdx | 11 ++-- .../migrate-from-0.2-to-0.3.mdx | 12 ++-- .../migrate-from-0.3-to-0.4.mdx | 4 +- .../migrate-from-0.5-to-0.6.mdx | 8 ++- pages/cloudflare/get-started.mdx | 25 ++++---- pages/cloudflare/howtos/assets.mdx | 6 +- pages/cloudflare/howtos/custom-worker.mdx | 7 +-- pages/cloudflare/howtos/db.mdx | 25 ++++---- pages/cloudflare/howtos/dev-deploy.mdx | 5 +- pages/cloudflare/howtos/env-vars.mdx | 3 +- pages/cloudflare/howtos/image.mdx | 9 +-- pages/cloudflare/howtos/keep_names.mdx | 4 +- pages/cloudflare/howtos/multi-worker.mdx | 16 +++-- pages/cloudflare/howtos/skew.mdx | 12 ++-- pages/cloudflare/howtos/workerd.mdx | 5 +- pages/cloudflare/index.mdx | 4 +- pages/cloudflare/perf.mdx | 8 +-- pages/cloudflare/troubleshooting.mdx | 15 +++-- pages/netlify/index.mdx | 2 +- 74 files changed, 277 insertions(+), 348 deletions(-) diff --git a/pages/aws/common_issues.mdx b/pages/aws/common_issues.mdx index aed21780..a8ae0e3d 100644 --- a/pages/aws/common_issues.mdx +++ b/pages/aws/common_issues.mdx @@ -4,7 +4,7 @@ OpenNext can be executed in debug mode by setting the environment variable `OPEN This will output **A LOT** of additional logs to the console.This also disable minifying in esbuild, and add source maps to the output. This can result in code that might be up to 2-3X larger than the production build. **Do not enable this in production** -```bash +```sh OPEN_NEXT_DEBUG=true npx open-next@latest build ``` @@ -16,7 +16,7 @@ You might stumble upon this error inside cloudwatch logs: `Cannot find module 'n Next might incorrectly include some dependencies in the bundle. To remove them you can use this configuration inside `next.config.js`: -```javascript +```js filename="next.config.js" outputFileTracingExcludes: { // or experimental.outputFileTracingExcludes on Next < 15 "*": ["node_modules/the-unwanted-package"], }, @@ -39,7 +39,7 @@ For example, Sentry does not remove server side sourcemaps, only client ones, ev You could exclude sourcemaps similarly: -```javascript +```js outputFileTracingExcludes: { "*": [ './**/*.js.map', @@ -96,9 +96,7 @@ The config recommended by Sentry docs uses dynamic imports in `instrumentation.t Here's a working Sentry config which resolves the error: -`instrumentation.ts` - -```typescript +```ts filename="instrumentation.ts" import * as Sentry from "@sentry/nextjs"; import { initSentry } from "../sentry.server.config"; @@ -109,9 +107,7 @@ export async function register() { } ``` -`sentry.server.config.ts` - -```typescript +```ts filename="sentry.server.config.ts" import * as Sentry from "@sentry/nextjs"; export const initSentry = (runtime: "nodejs" | "edge") => { @@ -141,7 +137,7 @@ If you are not using `yarn` and you see `yarn` related errors it might be solved Sometimes there might be a file missing from your server functions bundle. An example could be `sentry.server.config.ts`. It can be any file or directory and it also accept globs. In Next there is an option to include files that were not picked up by tracing. Its called `outputFileTracingIncludes`. Here is an example on how to use it in `next.config.ts`: -```ts +```ts filename="next.config.ts" import type { NextConfig } from "next"; const nextConfig: NextConfig = { @@ -162,8 +158,7 @@ To read more about `outputFileTracingIncludes` you can refer to the [Next.js doc It works with function splitting in OpenNext aswell. If your key corresponds to a specific route (i.e: `api/test`), it will be included only in the function bundle for that route. Using `*` as a key, however, will include it in every function bundle. Here is an example with function splitting: -```ts -// open-next.config.ts +```ts filename="open-next.config.ts" import type { OpenNextConfig } from "@opennextjs/aws/types/open-next"; const config = { default: {}, @@ -178,8 +173,9 @@ const config = { }, }, } satisfies OpenNextConfig; +``` -// next.config.ts +```ts filename="next.config.ts" import type { NextConfig } from "next"; const nextConfig: NextConfig = { diff --git a/pages/aws/config.mdx b/pages/aws/config.mdx index fc9811d5..59b8a084 100644 --- a/pages/aws/config.mdx +++ b/pages/aws/config.mdx @@ -13,7 +13,7 @@ This file needs to be placed at the same level as your `next.config.js` file. If you have an `open-next.config.ts` file, make sure you have atleast this: -```ts +```ts filename="open-next.config.ts" export default { default: {}, }; @@ -29,7 +29,7 @@ If you want to look at a full example, you can check [the full example](/aws/con By default Next.js will add the [`x-powered-by`](https://nextjs.org/docs/app/api-reference/config/next-config-js/poweredByHeader) header. OpenNext will also add a header `x-opennext`. To opt-out of this, open `next.config.js` and disable the poweredByHeader property in the configuration: -```ts +```js filename="next.config.js" module.exports = { poweredByHeader: false, }; diff --git a/pages/aws/config/custom_overrides.mdx b/pages/aws/config/custom_overrides.mdx index 7963e793..c9b29ca9 100644 --- a/pages/aws/config/custom_overrides.mdx +++ b/pages/aws/config/custom_overrides.mdx @@ -4,7 +4,7 @@ In some cases the simple example is not enough, and you want to add more customi Be careful if you use the edge runtime (either in a function or by using the external middleware), we do 2 compilations of the `open-next.config.ts`, one for node and one for the edge runtime. If you're using some custom overrides, you likely want to add -```ts +```ts filename="open-next.config.ts" edgeExternals: ['./customWrapper', './anyOtherOverrideUsed'] ``` to your `open-next.config.ts` to avoid the edge runtime to try to compile overrides that are not compatible with the edge runtime. @@ -17,8 +17,7 @@ Sometimes you might want to modify the object received by OpenNext. For example You'll still have to use a fallback value during dev as this is not used by the dev server. -```ts -// customConverter.ts +```ts filename="customConverter.ts" import converter from "@opennextjs/aws/overrides/converters/aws-apigw-v2.js"; import type { Converter } from "@opennextjs/aws/types/overrides.js"; import { Config } from "sst/node/Config"; @@ -50,8 +49,7 @@ export default { } as Converter; ``` -```ts -// open-next.config.ts +```ts filename="open-next.config.ts" import type { OpenNextConfig } from "@opennextjs/aws/types/open-next.js"; const config = { @@ -69,8 +67,7 @@ Here we provide a few examples for some custom wrapper. ### Define a global to use node in the middleware -```ts -// customWrapper.ts +```ts filename="customWrapper.ts" import defaultWrapper from "@opennextjs/aws/overrides/wrappers/aws-lambda.js"; //Here you can define some globals @@ -87,8 +84,7 @@ globalThis.myApi = async () => { export default defaultWrapper; ``` -```ts -// open-next.config.ts +```ts filename="open-next.config.ts" import type { OpenNextConfig } from "@opennextjs/aws/types/open-next.js"; const config = { default: { @@ -102,8 +98,7 @@ export default config; But since Next dev server runs in a fake edge runtime and that the global is defined only for deployment, you'll have to mock the global in your middleware. -```ts -// middleware.ts +```ts filename="middleware.ts" import { NextResponse } from "next/server"; import type { NextRequest } from "next/server"; @@ -135,8 +130,7 @@ export function middleware(request: NextRequest) { ### Use middy.js with the wrapper -```ts -// customWrapper.ts +```ts filename="customWrapper.ts" import streamingWrapper from "@opennextjs/aws/overrides/wrappers/aws-lambda.js"; import type { WrapperHandler } from "@opennextjs/aws/types/overrides.js"; import middy from "@middy/core"; @@ -154,8 +148,7 @@ export default { }; ``` -```ts -// open-next.config.ts +```ts filename="open-next.config.ts" import type { OpenNextConfig } from "@opennextjs/aws/types/open-next.js"; const config = { default: { @@ -173,8 +166,7 @@ In this example the custom wrapper is used to preload some important routes befo **WARNING**: This one is not properly tested. It's just an example of what you could do. You should test it properly before using it in production. Also preloading too many routes is probably a bad idea. -```ts -// customWrapper.ts +```ts filename="customWrapper.ts" import type { APIGatewayProxyEventV2, APIGatewayProxyResultV2 } from "aws-lambda"; import { Writable } from "node:stream"; @@ -251,8 +243,7 @@ export default { }; ``` -```ts -// open-next.config.ts +```ts filename="open-next.config.ts" import type { OpenNextConfig } from "@opennextjs/aws/types/open-next.js"; const config = { default: { @@ -267,7 +258,7 @@ const config = { You can take inspiration from our [`fs-dev`](https://github.com/opennextjs/opennextjs-aws/blob/main/packages/open-next/src/overrides/incrementalCache/fs-dev.ts) override which uses the file system to store the incremental cache. You need an `open-next.config.ts` with this: -```ts +```ts filename="open-next.config.ts" import type { OpenNextConfig } from "@opennextjs/aws/types/open-next.ts"; const config = { default: { @@ -287,7 +278,7 @@ export default config; By default it will use SQS queue to revalidate stale routes. You can read more about this [here](/aws/config/overrides/queue). To create your own custom override you can take inspiration by looking at our [included](https://github.com/opennextjs/opennextjs-aws/tree/main/packages/open-next/src/overrides/queue) implementations. You need an `open-next.config.ts` with this: -```ts +```ts filename="open-next.config.ts" import type { OpenNextConfig } from "@opennextjs/aws/types/open-next.ts"; const config = { default: { @@ -307,7 +298,7 @@ export default config; To override the tag cache you can take inspiration by looking at the [`fs-dev`](https://github.com/opennextjs/opennextjs-aws/blob/main/packages/open-next/src/overrides/tagCache/fs-dev.ts) override that uses the filesystem. You can read more about this override [here](/aws/config/overrides/tag_cache). You need an `open-next.config.ts` with this: -```ts +```ts filename="open-next.config.ts" import type { OpenNextConfig } from "@opennextjs/aws/types/open-next.ts"; const config = { default: { @@ -327,7 +318,7 @@ export default config; This override is only used internally by OpenNext to resolve the origin of the request if you have an `external` middleware. You can take inspiration from looking at our included [`pattern-env`](https://github.com/opennextjs/opennextjs-aws/blob/main/packages/open-next/src/overrides/originResolver/pattern-env.ts) override. You need an `open-next.config.ts` with this: -```ts +```ts filename="open-next.config.ts" import type { OpenNextConfig } from "@opennextjs/aws/types/open-next.js"; const config = { default: {}, @@ -348,7 +339,7 @@ export default config; This override is used in the image optimization server to load an image from a custom source. You can look at our implemention of using the file system [here](https://github.com/opennextjs/opennextjs-aws/blob/main/packages/open-next/src/overrides/imageLoader/fs-dev.ts). You need an `open-next.config.ts` with this: -```ts +```ts filename="open-next.config.ts" import type { OpenNextConfig } from "@opennextjs/aws/types/open-next.js"; const config = { default: {}, @@ -366,7 +357,7 @@ export default config; To have a custom override for the warmer invoke you can take inspiration by looking at our [`aws-lambda`](https://github.com/opennextjs/opennextjs-aws/blob/main/packages/open-next/src/overrides/warmer/aws-lambda.ts) override. You need an `open-next.config.ts` with this: -```ts +```ts filename="open-next.config.ts" import type { OpenNextConfig } from "@opennextjs/aws/types/open-next.js"; const config = { default: {}, @@ -384,7 +375,7 @@ export default config; To have a custom override for the CDN Invalidation you can take inspiration by looking at our [`cloudfront`](https://github.com/opennextjs/opennextjs-aws/tree/main/packages/open-next/src/overrides/cdnInvalidation/cloudfront.ts) override. You need an `open-next.config.ts` with this: -```ts +```ts filename="open-next.config.ts" import type { OpenNextConfig } from "@opennextjs/aws/types/open-next.js"; const config = { default: { @@ -403,7 +394,7 @@ export default config; This is used by OpenNext to proxy rewritten requests to external services. You can read more about it [here](/aws/config/overrides/proxy_external_request). To have a custom override for the External Request Proxy you can take inspiration by looking at our [`fetch`](https://github.com/opennextjs/opennextjs-aws/blob/main/packages/open-next/src/overrides/proxyExternalRequest/fetch.ts) override. You need an `open-next.config.ts` with this: -```ts +```ts filename="open-next.config.ts" import type { OpenNextConfig } from "@opennextjs/aws/types/open-next.js"; const config = { default: { @@ -422,7 +413,7 @@ export default config; This is used by OpenNext to resolve static assets. You can read more about it [here](/aws/config/overrides/asset_resolver). To have a custom override for the Asset Resolver, you need an `open-next.config.ts` with this: -```ts +```ts filename="open-next.config.ts" import type { OpenNextConfig } from "@opennextjs/aws/types/open-next.js"; const config = { default: {}, diff --git a/pages/aws/config/full_example.mdx b/pages/aws/config/full_example.mdx index fd45da4e..3611898e 100644 --- a/pages/aws/config/full_example.mdx +++ b/pages/aws/config/full_example.mdx @@ -4,7 +4,7 @@ Here is a detailed example of an `open-next.config.ts` file. This file need to b For more information about the options here, take a look at the [reference section](/aws/config/reference). -```ts +```ts filename="open-next.config.ts" import type { OpenNextConfig } from "@opennextjs/aws/types/open-next"; const config = { default: { diff --git a/pages/aws/config/nx.mdx b/pages/aws/config/nx.mdx index 0aa7e552..616f377f 100644 --- a/pages/aws/config/nx.mdx +++ b/pages/aws/config/nx.mdx @@ -6,7 +6,7 @@ Here's a detailed exampled of how to add OpenNext + SST to an existing Nx worksp 2. Update your `apps/next-site/next.config.js` add `output: ‘standalone’`, and you want to add `experimental.outputFileTracingRoot`, it should look a little like this: -```javascript +```js filename="next.config.js" //@ts-check // eslint-disable-next-line @typescript-eslint/no-var-requires @@ -39,7 +39,7 @@ module.exports = composePlugins(...plugins)(nextConfig); 3. Create `open-next.config.ts` inside your apps root directory, it should look a little something like this: -```javascript +```ts filename="open-next.config.ts" import type { OpenNextConfig } from '@opennextjs/aws/types/open-next'; const config = { @@ -134,7 +134,7 @@ but we will not use the SST cli to init this project, because it wants to add a - let's add the sst package with `pnpm add sst@ion`, and the required packages for SST to work with AWS `pnpm add --save-dev aws-cdk-lib constructs @types/aws-lambda` - then we want to manually create an `sst.config.ts` file in `apps/next-site` that looks like this: -```typescript +```ts filename="sst.config.ts" /// export default $config({ @@ -155,7 +155,7 @@ export default $config({ - now, you probably see some type errors, as SST is not initialized yet, but we can resolve this by running -```bash +```sh $ cd apps/next-site && sst install ``` @@ -252,7 +252,7 @@ this will resolve the type issues and initialize SST. now we can run (or if you want a custom stage, you can simply do `nx deploy next-site --stage this-is-my-stage` and it will be passed directly to the sst command). -```bash +```sh $ nx deploy next-site --configuration dev # using dev configuration (which sets the stage to development) # nx deploy next-site -c dev # OR # nx deploy next-site --stage my-stage # Custom Stage diff --git a/pages/aws/config/reference.mdx b/pages/aws/config/reference.mdx index 880d1368..cad02f40 100644 --- a/pages/aws/config/reference.mdx +++ b/pages/aws/config/reference.mdx @@ -81,7 +81,7 @@ Each server config will be under it's own key in the config object. Here are all Here is an example of how to install sharp on your default server function with ARM64 architecture: - ```ts + ```ts filename="open-next.config.ts" import type { OpenNextConfig } from '@opennextjs/aws/types/open-next'; const config = { default: { diff --git a/pages/aws/config/simple_example.mdx b/pages/aws/config/simple_example.mdx index bf981b82..4bf013a6 100644 --- a/pages/aws/config/simple_example.mdx +++ b/pages/aws/config/simple_example.mdx @@ -10,7 +10,7 @@ Here you can find the most common `open-next.config.ts` file examples that you c let them know of the issue. -```ts +```ts filename="open-next.config.ts" import type { OpenNextConfig } from "@opennextjs/aws/types/open-next.js"; const config = { default: { @@ -29,7 +29,7 @@ Be aware that there has been some issues in the past with AWS breaking streaming ## Splitting the server -```ts +```ts filename="open-next.config.ts" import type { OpenNextConfig } from "@opennextjs/aws/types/open-next.js"; const config = { // This is the default server, similar to the server-function in open-next v2 @@ -62,7 +62,7 @@ export default config; 300ms. Requires `OpenNext v3.0.3+`. Here is how you enable it: -```ts +```ts filename="open-next.config.ts" import type { OpenNextConfig } from "@opennextjs/aws/types/open-next.js"; const config = { default: { @@ -79,7 +79,7 @@ export default config; ## Running in Lambda@Edge -```ts +```ts filename="open-next.config.ts" import type { OpenNextConfig } from "@opennextjs/aws/types/open-next.js"; const config = { default: { @@ -102,7 +102,7 @@ Be aware that this uses the exact same system for ISR/SSG as the default lambda -```ts +```ts filename="open-next.config.ts" import type { OpenNextConfig } from "@opennextjs/aws/types/open-next.js"; const config = { // In this case, the default server is meant to run as a classic Node server @@ -137,7 +137,7 @@ This will generate 2 server functions, the default one and the edge one. The edg Edge runtime function have less cold start time, but you can only deploy one route per function. They also do not have the middleware bundled in the function, so you need to use external middleware if you need it in front of the edge function. -```ts +```ts filename="open-next.config.ts" import type { OpenNextConfig } from "@opennextjs/aws/types/open-next.js"; const config = { default: {}, @@ -160,7 +160,7 @@ In some cases (edge runtime, function splitting with some middleware rewrites, e With the default middleware configuration, it is bundled for a deployment in lambda@edge. This is how you can do it: -```ts +```ts filename="open-next.config.ts" import type { OpenNextConfig } from "@opennextjs/aws/types/open-next.js"; const config = { default: {}, diff --git a/pages/aws/contribute.mdx b/pages/aws/contribute.mdx index eb47b236..74866e6a 100644 --- a/pages/aws/contribute.mdx +++ b/pages/aws/contribute.mdx @@ -2,16 +2,16 @@ To run `OpenNext` locally: 1. Clone [this repository](https://github.com/opennextjs/opennextjs-aws). 2. Build `open-next`: - ```bash + ```sh cd opennextjs-aws pnpm build ``` 3. Run `open-next` in watch mode: - ```bash + ```sh pnpm dev ``` 4. Now, you can make changes in `open-next` and build your Next.js app to test the changes. - ```bash + ```sh cd path/to/my/nextjs/app path/to/opennextjs-aws/packages/open-next/dist/index.js build ``` diff --git a/pages/aws/contribute/local_run.mdx b/pages/aws/contribute/local_run.mdx index cd4f5813..2656d59f 100644 --- a/pages/aws/contribute/local_run.mdx +++ b/pages/aws/contribute/local_run.mdx @@ -2,7 +2,7 @@ When making some changes to OpenNext, it can be a bit cumbersome to need to depl To run `OpenNext` locally: -```bash +```sh # This is to build (the config-path is needed if you use a different name than the default one) node /path/to/opennextjs-aws/packages/open-next/dist/index.js build --config-path open-next.local.config.ts # Then to run the server @@ -11,8 +11,7 @@ node .open-next/server-functions/default/index.mjs ### open-next.local.config.ts -```typescript -// open-next.local.config.ts - +```ts filename="open-next.local.config.ts" // A good practice would be to use a different name so that it doesn't conflict // with your existing open-next.config.ts i.e. open-next.local.config.ts // You could also customize it by using custom overrides if you need to. diff --git a/pages/aws/contribute/plugin.mdx b/pages/aws/contribute/plugin.mdx index 1b92d733..717e9126 100644 --- a/pages/aws/contribute/plugin.mdx +++ b/pages/aws/contribute/plugin.mdx @@ -6,7 +6,7 @@ This plugin is used to replace some code in the source code with some other code Here is a very simple example of how to use it: -```typescript +```ts openNextPlugin({ // The target file to replace code in target: /plugins\/default\.js/g, @@ -42,7 +42,7 @@ This plugin is used to avoid having to bundle the whole library in the final bun Here is a very simple example of how to use it: -```typescript +```ts openNextResolvePlugin({ overrides: { wrapper: "node", @@ -57,7 +57,7 @@ This plugin is used to properly compile routes or middleware built for the `edge Here is a very simple example of how to use it: -```typescript +```ts openNextEdgePlugin({ // The path to the .next directory nextDir: "next", diff --git a/pages/aws/get_started.mdx b/pages/aws/get_started.mdx index 2aab40cc..ebbc3060 100644 --- a/pages/aws/get_started.mdx +++ b/pages/aws/get_started.mdx @@ -23,7 +23,7 @@ The OpenNext community has contributed deployment options for a few other framew To use these, you'll need to run the following inside your Next.js app. -```bash +```sh $ npx @opennextjs/aws@latest build ``` diff --git a/pages/aws/inner_workings.mdx b/pages/aws/inner_workings.mdx index f6f8ec7c..f1488d99 100644 --- a/pages/aws/inner_workings.mdx +++ b/pages/aws/inner_workings.mdx @@ -8,7 +8,7 @@ OpenNext runs the `build` script in your `package.json` file. Depending on the l The build output is then transformed into a format that can be deployed to AWS. The transformed output is generated inside the `.open-next` folder within your Next.js app. Files in `assets/` are ready to be uploaded to AWS S3. And the function code is wrapped inside Lambda handlers, ready to be deployed to AWS Lambda or Lambda@Edge. -```bash +```sh my-next-app/ .open-next/ cache/ -> ISR cache files to upload - This cannot be directly served diff --git a/pages/aws/inner_workings/architecture.mdx b/pages/aws/inner_workings/architecture.mdx index f8e09edd..34cc6fd1 100644 --- a/pages/aws/inner_workings/architecture.mdx +++ b/pages/aws/inner_workings/architecture.mdx @@ -20,7 +20,7 @@ There are two types of files in the `.open-next/assets` folder: These are files with a hash component in the file name. Hashed files are be found in the `.open-next/assets/_next` folder, such as `.open-next/assets/_next/static/css/0275f6d90e7ad339.css`. The hash values in the filenames are guaranteed to change when the content of the files is modified. Therefore, hashed files should be cached both at the CDN level and at the browser level. The recommended cache control setting for these file is -``` +```plain public,max-age=31536000,immutable ``` @@ -28,7 +28,7 @@ public,max-age=31536000,immutable Other files inside the `.open-next/assets` folder are copied from your app's `public/` folder, such as `.open-next/assets/favicon.ico`. The filename for un-hashed files may remain unchanged when the content is modified. Un-hashed files should be cached at the CDN level, but not at the browser level. When the content of un-hashed files is modified, the CDN cache should be invalidated on deploy. The recommended cache control setting for these file is -``` +```plain public,max-age=0,s-maxage=31536000,must-revalidate ``` @@ -53,7 +53,7 @@ See [Image Optimization](components/image_optimization) for more details. These backends handles all other types of requests from the Next.js app, including Server-side Rendering (SSR) requests, Incremental Static Regeneration (ISR) requests, Static Site Generation requests (SSG) and API requests. OpenNext builds the Next.js app in **standalone** mode. The standalone mode generates a `.next` folder containing the **NextServer** class that handles requests and a `node_modules` folder with **all the dependencies** needed to run the `NextServer`. The structure looks like this: -``` +```plain .next/ -> NextServer node_modules/ -> dependencies ``` @@ -71,7 +71,7 @@ The server backend adapter wraps around `NextServer` and exports a handler funct In the case of a monorepo, the build output looks slightly different. For example, if the app is located in `packages/web`, the build output looks like this: -``` +```plain packages/ web/ .next/ -> NextServer diff --git a/pages/aws/inner_workings/cache_interception.mdx b/pages/aws/inner_workings/cache_interception.mdx index 7aa0e56f..75f2e815 100644 --- a/pages/aws/inner_workings/cache_interception.mdx +++ b/pages/aws/inner_workings/cache_interception.mdx @@ -15,8 +15,7 @@ This has the following benefits: To enable cache interception, you need to add `enableCacheInterception` option in the `open-next.config.ts` file. -```ts -// open-next.config.ts +```ts filename="open-next.config.ts" import type { OpenNextConfig } from "@opennextjs/aws/types/open-next.js"; const config = { default: {}, diff --git a/pages/aws/inner_workings/caching.mdx b/pages/aws/inner_workings/caching.mdx index 2344ecd6..a3439ab6 100644 --- a/pages/aws/inner_workings/caching.mdx +++ b/pages/aws/inner_workings/caching.mdx @@ -23,8 +23,7 @@ They use this header by default `s-maxage=YOUR_REVALIDATION_TIME, stale-while-re When you manually revalidate the Next.js cache for a specific page, the ISR cache files stored on S3 will be updated. However, it is still necessary to invalidate the CloudFront cache: -```ts -// pages/api/revalidate.js +```js filename="pages/api/revalidate.js" export default async function handler(req, res) { await res.revalidate("/foo"); await invalidateCloudFrontPaths(["/foo"]); diff --git a/pages/aws/inner_workings/components/image_optimization.mdx b/pages/aws/inner_workings/components/image_optimization.mdx index b80f59ab..6515ea68 100644 --- a/pages/aws/inner_workings/components/image_optimization.mdx +++ b/pages/aws/inner_workings/components/image_optimization.mdx @@ -18,7 +18,7 @@ It is used to load **internal** images. By default, it uses S3 API to load the i You can customize the loader by providing a custom loader function to the `loader` prop. It should return -```typescript +```ts type ImageLoader = BaseOverride & { load: (url: string) => Promise<{ body?: Readable; diff --git a/pages/aws/inner_workings/components/initializer.mdx b/pages/aws/inner_workings/components/initializer.mdx index 11bb84d8..a4a3e1d6 100644 --- a/pages/aws/inner_workings/components/initializer.mdx +++ b/pages/aws/inner_workings/components/initializer.mdx @@ -2,7 +2,7 @@ The Initializer is a special backend that should run only once during deployment It uses these events and results: -```typescript +```ts interface InitializationFunctionEvent { type: "initializationFunction"; requestType: "create" | "update" | "delete"; diff --git a/pages/aws/inner_workings/components/middleware.mdx b/pages/aws/inner_workings/components/middleware.mdx index d3327e6d..96099c2c 100644 --- a/pages/aws/inner_workings/components/middleware.mdx +++ b/pages/aws/inner_workings/components/middleware.mdx @@ -10,7 +10,7 @@ Since V3, you can decide to move the middleware outside of the server into it's By default, the middleware is inside the server, but you can move it outside by setting `middleware.external` to `true` in your `open-next.config.ts` file. -```ts +```ts filename="open-next.config.ts" { middleware: { external: true; @@ -29,7 +29,7 @@ Since your app could be split into different origins, you need to be able to ret By default, it uses the `pattern-env` resolver which uses an `OPEN_NEXT_ORIGIN` environment variable to resolve the origin as well as the pattern defined in your `open-next.config.ts`. This env var should be a stringified version of an object of this shape: -```ts +```ts filename="open-next.config.ts" { // Key should be the same as the one used in `open-next.config.ts` for the functions [origin: string]: { @@ -44,7 +44,7 @@ By default, it uses the `pattern-env` resolver which uses an `OPEN_NEXT_ORIGIN` You can of course override this behavior by providing your own `originResolver` function in your `open-next.config.ts` file. This is the type of the `originResolver` function: -```ts +```ts filename="open-next.config.ts" type OriginResolver = BaseOverride & { resolve: (path: string) => Promise; }; diff --git a/pages/aws/inner_workings/components/overview.mdx b/pages/aws/inner_workings/components/overview.mdx index 804782e9..d415d6f0 100644 --- a/pages/aws/inner_workings/components/overview.mdx +++ b/pages/aws/inner_workings/components/overview.mdx @@ -30,7 +30,7 @@ All these backends can be overridden to fit your needs. They share some common g Every custom overrides (not `string`) share a `BaseOverride` types and needs to be wrapped this way: -```typescript +```ts type BaseOverride = { name: string; }; @@ -43,7 +43,7 @@ type LazyLoadedOverride = () => Promise; The wrapper is the main entrypoint for the backend. This is the type of the wrapper: -```typescript +```ts type WrapperHandler< E extends BaseEventOrResult = InternalEvent, R extends BaseEventOrResult = InternalResult, @@ -77,7 +77,7 @@ Be aware that you might encounter some unexpected behaviors when using streaming The converter is used to convert the event and the result. This is the type of the converter: -```typescript +```ts export type Converter< E extends BaseEventOrResult = InternalEvent, R extends BaseEventOrResult = InternalResult, diff --git a/pages/aws/inner_workings/components/revalidation.mdx b/pages/aws/inner_workings/components/revalidation.mdx index f2136e3f..181d25d0 100644 --- a/pages/aws/inner_workings/components/revalidation.mdx +++ b/pages/aws/inner_workings/components/revalidation.mdx @@ -3,7 +3,7 @@ For every received message it will trigger a `HEAD` request with `x-prerender-re ### Special Event and Result types -```typescript +```ts interface RevalidateEvent { type: "revalidate"; records: { diff --git a/pages/aws/inner_workings/components/server/node.mdx b/pages/aws/inner_workings/components/server/node.mdx index 9d377d43..69287322 100644 --- a/pages/aws/inner_workings/components/server/node.mdx +++ b/pages/aws/inner_workings/components/server/node.mdx @@ -75,7 +75,7 @@ The default DynamoDB Tag Cache uses the `@aws-sdk/client-dynamodb` to interact w Tags in DynamoDB should follow the following structure: -```typescript +```ts type Tag = { path: string; // The path of the page tag: string; // The tag of the page diff --git a/pages/aws/inner_workings/components/warmer.mdx b/pages/aws/inner_workings/components/warmer.mdx index 960e46b6..6f77dd6e 100644 --- a/pages/aws/inner_workings/components/warmer.mdx +++ b/pages/aws/inner_workings/components/warmer.mdx @@ -2,7 +2,7 @@ The warmer backend is used to warm up the server lambda in case of serverless. T ### Special Event and Result -```typescript +```ts interface WarmerEvent { type: "warmer"; warmerId: string; @@ -23,7 +23,7 @@ interface WarmerResponse { You can customize the `invoke` function to handle the `warmer` event. By default it uses lambda invoke command. The default invoke needs a `WARM_PARAMS` environment variable that is a stringified version of this -```typescript +```ts { concurrency: number; function: string; diff --git a/pages/aws/inner_workings/routing.mdx b/pages/aws/inner_workings/routing.mdx index fcb4cb68..6684f6a1 100644 --- a/pages/aws/inner_workings/routing.mdx +++ b/pages/aws/inner_workings/routing.mdx @@ -22,7 +22,9 @@ The Next middleware in OpenNext is not running in the same way as in Next.js. In On latest Next 15(works with latest OpenNext aswell) you can now add an `experimental` setting in `next.config.ts` to enable `nodejs` as the runtime for the middleware: -```ts +```ts filename="next.config.ts" +import type { NextConfig } from "next"; + const nextConfig: NextConfig = { experimental: { nodeMiddleware: true, diff --git a/pages/aws/migration.mdx b/pages/aws/migration.mdx index 4d3d90cf..f1b0d2d3 100644 --- a/pages/aws/migration.mdx +++ b/pages/aws/migration.mdx @@ -32,7 +32,7 @@ TODO You should remove some stuff from your `next.config.js` file, otherwise you'll get a build error.: -```js +```js filename="next.config.js" module.exports = { // ... target: "serverless", // remove this diff --git a/pages/aws/v2/advanced/architecture.mdx b/pages/aws/v2/advanced/architecture.mdx index 31b79f80..86f4a839 100644 --- a/pages/aws/v2/advanced/architecture.mdx +++ b/pages/aws/v2/advanced/architecture.mdx @@ -20,7 +20,7 @@ There are two types of files in the `.open-next/assets` folder: These are files with a hash component in the file name. Hashed files are be found in the `.open-next/assets/_next` folder, such as `.open-next/assets/_next/static/css/0275f6d90e7ad339.css`. The hash values in the filenames are guaranteed to change when the content of the files is modified. Therefore, hashed files should be cached both at the CDN level and at the browser level. When uploading the hashed files to S3, the recommended cache control setting is -``` +```plain public,max-age=31536000,immutable ``` @@ -28,7 +28,7 @@ public,max-age=31536000,immutable Other files inside the `.open-next/assets` folder are copied from your app's `public/` folder, such as `.open-next/assets/favicon.ico`. The filename for un-hashed files may remain unchanged when the content is modified. Un-hashed files should be cached at the CDN level, but not at the browser level. When the content of un-hashed files is modified, the CDN cache should be invalidated on deploy. When uploading the un-hashed files to S3, the recommended cache control setting is -``` +```plain public,max-age=0,s-maxage=31536000,must-revalidate ``` @@ -79,7 +79,7 @@ Create a Lambda function using the code in the `.open-next/server-function` fold This function handles all other types of requests from the Next.js app, including Server-side Rendering (SSR) requests and API requests. OpenNext builds the Next.js app in **standalone** mode. The standalone mode generates a `.next` folder containing the **NextServer** class that handles requests and a `node_modules` folder with **all the dependencies** needed to run the `NextServer`. The structure looks like this: -``` +```plain .next/ -> NextServer node_modules/ -> dependencies ``` @@ -97,7 +97,7 @@ The server function adapter wraps around `NextServer` and exports a handler func In the case of a monorepo, the build output looks slightly different. For example, if the app is located in `packages/web`, the build output looks like this: -``` +```plain packages/ web/ .next/ -> NextServer diff --git a/pages/aws/v2/advanced/debugging.mdx b/pages/aws/v2/advanced/debugging.mdx index 6c6dcc23..fd08987d 100644 --- a/pages/aws/v2/advanced/debugging.mdx +++ b/pages/aws/v2/advanced/debugging.mdx @@ -8,7 +8,7 @@ If the server function is **deployed to Lambda@Edge**, the logs will appear in t The logs from the warmer function provide insights into the results of the warming process. -``` +```json { event: 'warmer result', sent: 2, success: 2, uniqueServersWarmed: 2 } ``` diff --git a/pages/aws/v2/advanced/options.mdx b/pages/aws/v2/advanced/options.mdx index d21cc69d..14960df3 100644 --- a/pages/aws/v2/advanced/options.mdx +++ b/pages/aws/v2/advanced/options.mdx @@ -2,13 +2,11 @@ OpenNext runs the `build` script in your `package.json` by default. However, you can specify a custom build command if required. -```bash -# CLI +```sh open-next build --build-command "pnpm custom:build" ``` -```ts -// JS +```js import { build } from "open-next/build.js"; await build({ @@ -20,13 +18,11 @@ await build({ OpenNext runs the `build` script from your current command folder by default. When running OpenNext from a monorepo with decentralised application and build output paths, you can specify a custom `appPath` and/or `buildOutputPath`. This will allow you to execute your command from the root of the monorepo. -```bash -# CLI +```sh open-next build --build-command "pnpm custom:build" --app-path "./apps/example-app" --build-output-path "./dist/apps/example-app" ``` -```ts -// JS +```js import { build } from "open-next/build.js"; await build({ @@ -40,13 +36,11 @@ await build({ Enabling this option will minimize all `.js` and `.json` files in the server function bundle using the [node-minify](https://github.com/srod/node-minify) library. This can reduce the size of the server function bundle by about 40%, depending on the size of your app. -```bash -# CLI +```sh open-next build --minify ``` -```ts -// JS +```js import { build } from "open-next/build.js"; await build({ @@ -62,7 +56,7 @@ Enabling this option will enable streaming support for the server function. This **Do not use this in production**. See [this](/v2/inner_workings/streaming) for more information. -```bash +```sh open-next build --streaming ``` @@ -70,7 +64,7 @@ open-next build --streaming Enabling this option will disable the dynamodb cache. This is experimental and needs to be opted into. This means that `next/cache` revalidation will not work. -```bash +```sh open-next build --dangerously-disable-dynamodb-cache ``` @@ -78,7 +72,7 @@ open-next build --dangerously-disable-dynamodb-cache Disabling incremental cache will cause the entire page to be revalidated on each request. This will cause ISR and SSG pages to be in an inconsistent state. Specify this option if you are using SSR pages only. This will also disable the dynamodb cache. -```bash +```sh open-next build --dangerously-disable-incremental-cache ``` @@ -102,13 +96,11 @@ Similarly, if you decide to upload cache files to a subfolder (ie. "cache"), be OpenNext can be executed in debug mode for bug tracking purposes. -```bash -# CLI +```sh OPEN_NEXT_DEBUG=true npx open-next@latest build ``` -```ts -// JS +```js import { build } from "open-next/build.js"; await build({ diff --git a/pages/aws/v2/advanced/workaround.mdx b/pages/aws/v2/advanced/workaround.mdx index 88bbec4e..2fffef61 100644 --- a/pages/aws/v2/advanced/workaround.mdx +++ b/pages/aws/v2/advanced/workaround.mdx @@ -2,7 +2,7 @@ As mentioned in the [Asset files](./architecture#asset-files) section, files in your app's `public/` folder are static and are uploaded to the S3 bucket. And requests for these files are handled by the S3 bucket, like so: -``` +```plain https://my-nextjs-app.com/favicon.ico https://my-nextjs-app.com/my-images/avatar.png ``` @@ -11,7 +11,7 @@ Ideally, we would create a single cache behavior that routes all requests for `p To work around this limitation, we create a separate cache behavior for each top-level file and folder in `public/`. For example, if your folder structure is: -``` +```plain public/ favicon.ico my-images/ @@ -25,7 +25,7 @@ You would create three cache behaviors: `/favicon.ico`, `/my-images/*`, and `/fo One thing to be aware of is that CloudFront has a [default limit of 25 behaviors per distribution](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/cloudfront-limits.html#limits-web-distributions). If you have a lot of top-level files and folders, you may reach this limit. To avoid this, consider moving some or all files and folders into a subdirectory: -``` +```plain public/ files/ favicon.ico @@ -115,7 +115,7 @@ As mentioned in the [Server function](./architecture#server-lambda-function) sec To work around the issue, the server function checks if the request is for a fully static HTML page from page router (i.e. without `getStaticProps`), and sets the `Cache Control` header to: -``` +```plain public, max-age=0, s-maxage=31536000, must-revalidate ``` @@ -126,7 +126,7 @@ You can also just add an empty `getStaticProps` function to your page, which wil `NextServer` does not seem to set an appropriate value for the `stale-while-revalidate` cache header. For example, the header might look like this: -``` +```plain s-maxage=600 stale-while-revalidate ``` @@ -134,7 +134,7 @@ This prevents CloudFront from caching the stale data. To work around the issue, the server function checks if the response includes the `stale-while-revalidate` header. If found, it sets the value to 30 days: -``` +```plain s-maxage=600 stale-while-revalidate=2592000 ``` @@ -142,7 +142,7 @@ s-maxage=600 stale-while-revalidate=2592000 Next.js recommends using `process.cwd()` instead of `__dirname` to get the app directory. For example, consider a `posts` folder in your app with markdown files: -``` +```plain pages/ posts/ my-post.md @@ -159,7 +159,7 @@ path.join(process.cwd(), "posts", "my-post.md"); As mentioned in the [Server function](./architecture#server-lambda-function) section, in a non-monorepo setup, the `server-function` bundle looks like: -``` +```plain .next/ node_modules/ posts/ @@ -171,7 +171,7 @@ In this case, `path.join(process.cwd(), "posts", "my-post.md")` resolves to the However, when the user's app is inside a monorepo (ie. at `/packages/web`), the `server-function` bundle looks like: -``` +```plain packages/ web/ .next/ diff --git a/pages/aws/v2/common_issues/bundle_size.mdx b/pages/aws/v2/common_issues/bundle_size.mdx index 31950cd3..dffb0583 100644 --- a/pages/aws/v2/common_issues/bundle_size.mdx +++ b/pages/aws/v2/common_issues/bundle_size.mdx @@ -13,7 +13,7 @@ Serverless environments are sensitive to bundle size, since it has to download a To identify the module that's taking up too much space (and isn't serverless friendly): -```bash +```sh du -hs .open-next/server-function/node_modules/* | sort -rh ``` diff --git a/pages/aws/v2/common_issues/isr.mdx b/pages/aws/v2/common_issues/isr.mdx index ea38dbfc..49f76d59 100644 --- a/pages/aws/v2/common_issues/isr.mdx +++ b/pages/aws/v2/common_issues/isr.mdx @@ -9,8 +9,7 @@ import { Callout } from "nextra/components"; When you manually revalidate the Next.js cache for a specific page, the ISR cache files stored on S3 will be updated. However, it is still necessary to invalidate the CloudFront cache: -```ts -// pages/api/revalidate.js +```js filename="pages/api/revalidate.js" export default async function handler(req, res) { await res.revalidate("/foo"); await invalidateCloudFrontPaths(["/foo"]); diff --git a/pages/aws/v2/inner_workings/isr.mdx b/pages/aws/v2/inner_workings/isr.mdx index 3f6e6532..b5c5acb9 100644 --- a/pages/aws/v2/inner_workings/isr.mdx +++ b/pages/aws/v2/inner_workings/isr.mdx @@ -53,14 +53,14 @@ For the examples here, let's assume an app route with a 5 minute revalidation de - Each `get` request to the cache will result in at least 1 `GetObject` -``` +```plain GetObject cost - 8,640 requests * $0.0004 per 1,000 requests = $0.003456 Total cost - $0.003456 per route per month ``` - Each `set` request to the cache will result in 1 `PutObject` in S3 -``` +```plain PutObject cost - 8,640 requests * $0.005 per 1,000 requests = $0.0432 Total cost - $0.0432 per route per month ``` @@ -73,7 +73,7 @@ For the example, let's consider that that same route has 2 tags and 10 paths and - Each `revalidateTag` request will result in 1 `Query` in DynamoDB and a `PutItem` for each path associated with the tag, they are grouped in batches of 25 in a `BatchWriteItem` request. -``` +```plain Assuming you do 1 revalidation per 5 minute Query cost - 8,640 request * $0.25 per 1,000,000 read = $0.00216 BatchWriteItem cost - 86,400 requests * $0.25 per 1,000,000 write = $0.0216 @@ -82,14 +82,14 @@ For the example, let's consider that that same route has 2 tags and 10 paths and - Each `get` request will result in 1 `Query` in DynamoDB -``` +```plain Query cost - 8,640 request * $0.25 per 1,000,000 read = $0.00216 Total cost - $0.00216 per route per month ``` - Each `set` request will result in 1 `Query` in DynamoDB and a `PutItem` for each tag associated with the path that are not present in DynamoDB, they are grouped in batches of 25 in a `BatchWriteItem` request. -``` +```plain Query cost - 8,640 request * $0.25 per 1,000,000 read = $0.00216 Total cost - $0.00216 per route per month ``` diff --git a/pages/aws/v2/inner_workings/plugin.mdx b/pages/aws/v2/inner_workings/plugin.mdx index 24579667..e22b3570 100644 --- a/pages/aws/v2/inner_workings/plugin.mdx +++ b/pages/aws/v2/inner_workings/plugin.mdx @@ -50,7 +50,7 @@ Do not include `types` in #override and #imports, as esbuild will remove preceed Instead, put the `import type` outside like: -``` +```ts import type { PluginHandler } from "../next-types.js"; import type { IncomingMessage } from "../request.js"; import type { ServerResponse } from "../response.js"; diff --git a/pages/aws/v2/inner_workings/streaming.mdx b/pages/aws/v2/inner_workings/streaming.mdx index 0013aac0..ac793d97 100644 --- a/pages/aws/v2/inner_workings/streaming.mdx +++ b/pages/aws/v2/inner_workings/streaming.mdx @@ -12,6 +12,6 @@ Streaming is using the new AWS lambda support for [streaming responses](https:// If you want to try streaming you need to set the function url invoke mode to `RESPONSE_STREAM`. You'll also need to add a `--streaming` tags to the build cli. -```bash +```sh open-next build --streaming ``` diff --git a/pages/aws/v2/inner_workings/warming.mdx b/pages/aws/v2/inner_workings/warming.mdx index 35c13e08..d12e8e74 100644 --- a/pages/aws/v2/inner_workings/warming.mdx +++ b/pages/aws/v2/inner_workings/warming.mdx @@ -18,27 +18,27 @@ There are three components to the cost: 1. EventBridge scheduler: $0.00864 - ``` + ```plain Requests cost — 8,640 invocations per month x $1/million = $0.00864 ``` 1. Warmer function: $0.145728288 - ``` + ```plain Requests cost — 8,640 invocations per month x $0.2/million = $0.001728 Duration cost — 8,640 invocations per month x 1GB memory x 1s duration x $0.0000166667/GB-second = $0.144000288 ``` 1. Server function: $0.0161280288 per warmed instance - ``` + ```plain Requests cost — 8,640 invocations per month x $0.2/million = $0.001728 Duration cost — 8,640 invocations per month x 1GB memory x 100ms duration x $0.0000166667/GB-second = $0.0144000288 ``` For example, keeping 50 instances of the server function warm will cost approximately **$0.96 per month** -``` +```plain $0.00864 + $0.145728288 + $0.0161280288 x 50 = $0.960769728 diff --git a/pages/cloudflare/bindings.mdx b/pages/cloudflare/bindings.mdx index eb172db6..5fd42db0 100644 --- a/pages/cloudflare/bindings.mdx +++ b/pages/cloudflare/bindings.mdx @@ -43,7 +43,7 @@ Add bindings to your Worker by adding them to your [wrangler configuration file] To ensure that the `env` object from `getCloudflareContext().env` above has accurate TypeScript types, run the following Wrangler command to [generate types that match your Worker's configuration](https://developers.cloudflare.com/workers/languages/typescript/#generate-types-that-match-your-workers-configuration-experimental): -``` +```sh npx wrangler types --env-interface CloudflareEnv ``` @@ -72,7 +72,7 @@ as documented in the [remote bindings documentation](https://developers.cloudfla The remote bindings APIs have been stabilized in wrangler `4.36.0`, so if you're using an earlier version of wrangler in order to use remote bindings you need to enabled it in your `next.config.ts` file: -```diff +```diff filename="next.config.ts" - initOpenNextCloudflareForDev(); + initOpenNextCloudflareForDev({ + experimental: { remoteBindings: true } diff --git a/pages/cloudflare/caching.mdx b/pages/cloudflare/caching.mdx index aa771a83..9b7f402c 100644 --- a/pages/cloudflare/caching.mdx +++ b/pages/cloudflare/caching.mdx @@ -44,7 +44,7 @@ You should use the following implementation for a small site: -```jsonc +```jsonc filename="wrangler.jsonc" { "name": "", // ... @@ -95,7 +95,7 @@ You should use the following implementation for a small site: -```ts +```ts filename="open-next.config.ts" import { defineCloudflareConfig } from "@opennextjs/cloudflare"; import r2IncrementalCache from "@opennextjs/cloudflare/overrides/incremental-cache/r2-incremental-cache"; import d1NextTagCache from "@opennextjs/cloudflare/overrides/tag-cache/d1-next-tag-cache"; @@ -127,7 +127,7 @@ For a larger site, you should use the `ShardedDOTagCache` that can handle a high -```jsonc +```jsonc filename="wrangler.jsonc" { "name": "", // ... @@ -182,7 +182,7 @@ For a larger site, you should use the `ShardedDOTagCache` that can handle a high -```ts +```ts filename="open-next.config.ts" import { defineCloudflareConfig } from "@opennextjs/cloudflare"; import r2IncrementalCache from "@opennextjs/cloudflare/overrides/incremental-cache/r2-incremental-cache"; import { withRegionalCache } from "@opennextjs/cloudflare/overrides/incremental-cache/regional-cache"; @@ -228,7 +228,7 @@ If your site is static, you do not need a Queue nor a Tag Cache. You can use a r -```ts +```ts filename="open-next.config.ts" import { defineCloudflareConfig } from "@opennextjs/cloudflare"; import staticAssetsIncrementalCache from "@opennextjs/cloudflare/overrides/incremental-cache/static-assets-incremental-cache"; @@ -258,7 +258,7 @@ By default, Cloudflare [Static Assets headers](https://developers.cloudflare.com Next.js also generates _immutable_ files that don't change between builds. Those files will also be served from Static Assets. To match the [default cache behavior of immutable assets in Next.js](https://nextjs.org/docs/app/guides/self-hosting#automatic-caching), avoiding unnecessary revalidation requests, add the following header to the [`public/_headers`](https://developers.cloudflare.com/workers/static-assets/headers/#custom-headers) file: -```txt +```plain filename="public/_headers" /_next/static/* Cache-Control: public,max-age=31536000,immutable ``` @@ -286,8 +286,7 @@ The binding name used in your app's worker is `NEXT_INC_CACHE_R2_BUCKET`. The se The prefix used by the R2 bucket can be configured with the `NEXT_INC_CACHE_R2_PREFIX` environment variable, and defaults to `incremental-cache`. -```jsonc -// wrangler.jsonc +```jsonc filename="wrangler.jsonc" { // ... "name": "", @@ -322,8 +321,7 @@ Additionally there are options you can use to customize the behavior of the regi - `shouldLazilyUpdateOnCacheHit`: Instructs the cache to be lazily updated, meaning that when requesting data from the cache, a background request is sent to the R2 bucket to get the latest entry. This is enabled by default for the `long-lived` mode. - `bypassTagCacheOnCacheHit`: Instructs the cache not to check the tag cache when there is a regional cache hit. This enables reducing response times. When this option is used you need to make sure that the cache gets correctly purged either by enabling the [automatic cache purge](#automatic-cache-purge) or purging the cache manually. Defaults to `false`. -```ts -// open-next.config.ts +```ts filename="open-next.config.ts" import { defineCloudflareConfig } from "@opennextjs/cloudflare"; import r2IncrementalCache from "@opennextjs/cloudflare/overrides/incremental-cache/r2-incremental-cache"; import { withRegionalCache } from "@opennextjs/cloudflare/overrides/incremental-cache/regional-cache"; @@ -366,8 +364,7 @@ The `WORKER_SELF_REFERENCE` service binding should be a self reference to your w The prefix used by the cache keys can be configured with the `NEXT_INC_CACHE_KV_PREFIX` environment variable, and defaults to `incremental-cache`. -```jsonc -// wrangler.jsonc +```jsonc filename="wrangler.jsonc" { // ... "name": "", @@ -390,8 +387,7 @@ The prefix used by the cache keys can be configured with the `NEXT_INC_CACHE_KV_ In your project's OpenNext config, enable the KV cache. -```ts -// open-next.config.ts +```ts filename="open-next.config.ts" import { defineCloudflareConfig } from "@opennextjs/cloudflare"; import kvIncrementalCache from "@opennextjs/cloudflare/overrides/incremental-cache/kv-incremental-cache"; // ... @@ -414,8 +410,7 @@ export default defineCloudflareConfig({ In your project's OpenNext config, enable the static assets cache. -```ts -// open-next.config.ts +```ts filename="open-next.config.ts" import { defineCloudflareConfig } from "@opennextjs/cloudflare"; import staticAssetsIncrementalCache from "@opennextjs/cloudflare/overrides/incremental-cache/static-assets-incremental-cache"; @@ -439,8 +434,7 @@ In your project's OpenNext config, enable the cache and set up a queue. The Durable Object Queue will send revalidation requests to a page when needed, and offers support for de-duplicating requests. By default there will be a maximum of 10 instance of the Durables Object Queue and they can each process up to 5 requests in parallel, for up to 50 concurrent ISR revalidations. -```ts -// open-next.config.ts +```ts filename="open-next.config.ts" import { defineCloudflareConfig } from "@opennextjs/cloudflare"; // ... import r2IncrementalCache from "@opennextjs/cloudflare/overrides/incremental-cache/r2-incremental-cache"; @@ -455,8 +449,9 @@ export default defineCloudflareConfig({ You will also need to add some binding to your `wrangler.jsonc` file. -```jsonc -"durable_objects": { +```jsonc filename="wrangler.jsonc" +{ + "durable_objects": { "bindings": [ { "name": "NEXT_CACHE_DO_QUEUE", @@ -470,6 +465,7 @@ You will also need to add some binding to your `wrangler.jsonc` file. "new_sqlite_classes": ["DOQueueHandler"] } ], +} ``` You can customize the behaviors of the queue with environment variables: @@ -495,8 +491,7 @@ You can customize the behaviors of the queue with environment variables: In certain situations, you may encounter the limits of what the Durable Object queue can manage for a single page or route. In such cases, you can utilize the queueCache to minimize the number of stale requests sent to the queue. This is achieved by adding and verifying a cache entry via the Cache API before dispatching a request to the queue. If a cache entry already exists, the request will not be sent to the queue, as it will be considered already in process. -```ts -// open-next.config.ts +```ts filename="open-next.config.ts" import { defineCloudflareConfig } from "@opennextjs/cloudflare"; // ... import r2IncrementalCache from "@opennextjs/cloudflare/overrides/incremental-cache/r2-incremental-cache"; @@ -543,8 +538,7 @@ If either of these factors is significant, opting for a sharded database is reco The binding name used in your app's worker is `NEXT_TAG_CACHE_D1`. The `WORKER_SELF_REFERENCE` service binding should be a self reference to your worker where `` is the name in your wrangler configuration file. -```jsonc -// wrangler.jsonc +```jsonc filename="wrangler.jsonc" { // ... "d1_databases": [ @@ -571,8 +565,7 @@ The D1 tag cache requires a `revalidations` table that tracks On-Demand revalida In your project's OpenNext config, enable the R2 cache and set up a queue (see above). The queue will send a revalidation request to a page when needed, but it will not dedupe requests. -```ts -// open-next.config.ts +```ts filename="open-next.config.ts" import { defineCloudflareConfig } from "@opennextjs/cloudflare"; import r2IncrementalCache from "@opennextjs/cloudflare/overrides/incremental-cache/r2-incremental-cache"; import doQueue from "@opennextjs/cloudflare/overrides/queue/do-queue"; @@ -598,8 +591,7 @@ To populate remote bindings and create a new [version](https://developers.cloudf The service binding should be a self reference to your worker where `` is the name in your wrangler configuration file. -```jsonc -// wrangler.jsonc +```jsonc filename="wrangler.jsonc" { // ... "durable_objects": { @@ -633,8 +625,7 @@ The service binding should be a self reference to your worker where ` ``` @@ -29,7 +29,7 @@ npx wrangler@latest kv namespace create The binding name used in your app's worker will be `NEXT_CACHE_WORKERS_KV` by default. This is configurable and can be changed by setting the `__OPENNEXT_KV_BINDING_NAME` build-time environment variable. -``` +```toml filename="wrangler.toml" [[kv_namespaces]] binding = "NEXT_CACHE_WORKERS_KV" id = "" diff --git a/pages/cloudflare/former-releases/0.2/examples.mdx b/pages/cloudflare/former-releases/0.2/examples.mdx index 6dd75b24..d19836a8 100644 --- a/pages/cloudflare/former-releases/0.2/examples.mdx +++ b/pages/cloudflare/former-releases/0.2/examples.mdx @@ -4,7 +4,7 @@ import { Callout } from "nextra/components"; To create a new Next.js app, pre-configured to run on Cloudflare using @opennextjs/cloudflare, run: -``` +```sh npm create cloudflare@latest -- my-next-app --framework=next --experimental ``` diff --git a/pages/cloudflare/former-releases/0.2/get-started.mdx b/pages/cloudflare/former-releases/0.2/get-started.mdx index 0616e70a..64662ddf 100644 --- a/pages/cloudflare/former-releases/0.2/get-started.mdx +++ b/pages/cloudflare/former-releases/0.2/get-started.mdx @@ -6,7 +6,7 @@ import { Callout } from "nextra/components"; To create a new Next.js app, pre-configured to run on Cloudflare using @opennextjs/cloudflare, run: -``` +```sh npm create cloudflare@latest -- my-next-app --framework=next --experimental ``` @@ -24,7 +24,7 @@ npm install --save-dev @opennextjs/cloudflare Install the [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/) as a devDependency: -```npm +```sh npm install -D wrangler@latest ``` @@ -34,7 +34,7 @@ npm install -D wrangler@latest Then, add a [`wrangler.toml`](https://developers.cloudflare.com/workers/wrangler/configuration/) file to the root directory of your Next.js app: -```toml +```toml filename="wrangler.toml" main = ".worker-next/index.mjs" name = "my-app" compatibility_date = "2024-09-23" @@ -55,7 +55,7 @@ assets = { directory = ".worker-next/assets", binding = "ASSETS" } Add the following to the scripts field of your `package.json` file: -```json +```json filename="package.json" "build:worker": "cloudflare", "dev:worker": "wrangler dev --port 8771", "preview:worker": "npm run build:worker && npm run dev:worker", @@ -89,7 +89,7 @@ You should uninstall `@cloudflare/next-on-pages` and remove any references to it In `package.json`: -```diff +```diff filename="package.json" "scripts": { - "pages:build": "npx @cloudflare/next-on-pages", - "preview": "npm run pages:build && wrangler pages dev", @@ -103,7 +103,7 @@ In `package.json`: You no longer need to call `setupDevPlatform()` in your `next.config.mjs` file: -```diff title="next.config.mjs" +```diff filename="next.config.mjs" - import { setupDevPlatform } from '@cloudflare/next-on-pages/next-dev'; /** @type {import('next').NextConfig} */ diff --git a/pages/cloudflare/former-releases/0.2/index.mdx b/pages/cloudflare/former-releases/0.2/index.mdx index a3f53c23..a5db6d35 100644 --- a/pages/cloudflare/former-releases/0.2/index.mdx +++ b/pages/cloudflare/former-releases/0.2/index.mdx @@ -17,7 +17,7 @@ You can also use [`@cloudflare/next-on-pages`](https://www.npmjs.com/package/@cl To create a new Next.js app, pre-configured to run on Cloudflare using @opennextjs/cloudflare, run: -``` +```sh npm create cloudflare@latest -- my-next-app --framework=next --experimental ``` diff --git a/pages/cloudflare/former-releases/0.3/bindings.mdx b/pages/cloudflare/former-releases/0.3/bindings.mdx index 1b3164d3..7d60eb32 100644 --- a/pages/cloudflare/former-releases/0.3/bindings.mdx +++ b/pages/cloudflare/former-releases/0.3/bindings.mdx @@ -34,7 +34,7 @@ Add bindings to your Worker by adding them to your [wrangler configuration file] To ensure that the `env` object from `(await getCloudflareContext()).env` above has accurate TypeScript types, run the following Wrangler command to [generate types that match your Worker's configuration](https://developers.cloudflare.com/workers/languages/typescript/#generate-types-that-match-your-workers-configuration-experimental): -``` +```sh npx wrangler types --experimental-include-runtime ``` @@ -42,7 +42,7 @@ This will generate a `d.ts` file and (by default) save it to `.wrangler/types/ru If you would like to commit the file to git, you can provide a custom path. Here, for instance, the `runtime.d.ts` file will be saved to the root of your project: -```bash +```sh npx wrangler types --experimental-include-runtime="./runtime.d.ts" ``` diff --git a/pages/cloudflare/former-releases/0.3/caching.mdx b/pages/cloudflare/former-releases/0.3/caching.mdx index 09b7b9a9..68a87bd0 100644 --- a/pages/cloudflare/former-releases/0.3/caching.mdx +++ b/pages/cloudflare/former-releases/0.3/caching.mdx @@ -25,7 +25,7 @@ To enable caching, you must: #### 1. Create a KV namespace -``` +```sh npx wrangler@latest kv namespace create ``` @@ -33,8 +33,7 @@ npx wrangler@latest kv namespace create The binding name used in your app's worker is `NEXT_CACHE_WORKERS_KV`. -```jsonc -// wrangler.json +```jsonc filename="wrangler.jsonc" { // ... "kv_namespaces": [ diff --git a/pages/cloudflare/former-releases/0.3/examples.mdx b/pages/cloudflare/former-releases/0.3/examples.mdx index e44bee0d..c156b6bb 100644 --- a/pages/cloudflare/former-releases/0.3/examples.mdx +++ b/pages/cloudflare/former-releases/0.3/examples.mdx @@ -4,7 +4,7 @@ import { Callout } from "nextra/components"; To create a new Next.js app, pre-configured to run on Cloudflare using `@opennextjs/cloudflare`, run: -``` +```sh npm create cloudflare@latest -- my-next-app --framework=next --experimental ``` diff --git a/pages/cloudflare/former-releases/0.3/get-started.mdx b/pages/cloudflare/former-releases/0.3/get-started.mdx index 0ade82d7..96dc8c5b 100644 --- a/pages/cloudflare/former-releases/0.3/get-started.mdx +++ b/pages/cloudflare/former-releases/0.3/get-started.mdx @@ -6,7 +6,7 @@ import { Callout } from "nextra/components"; To create a new Next.js app, pre-configured to run on Cloudflare using `@opennextjs/cloudflare`, run: -``` +```sh npm create cloudflare@latest -- my-next-app --framework=next --experimental ``` @@ -24,7 +24,7 @@ npm install --save-dev @opennextjs/cloudflare@latest Install the [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/) as a devDependency: -```npm +```sh npm install --save-dev wrangler@latest ``` @@ -42,9 +42,9 @@ npm install --save-dev wrangler@latest A [wrangler configuration file](https://developers.cloudflare.com/workers/wrangler/configuration/) 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 in the root directory of your Next.js app with the name `wrangler.json` and the following content: +You can create one yourself in the root directory of your Next.js app with the name `wrangler.jsonc` and the following content: -```jsonc +```jsonc filename="wrangler.jsonc" { "$schema": "node_modules/wrangler/config-schema.json", "main": ".open-next/worker.js", @@ -85,7 +85,7 @@ You can create one yourself in the root directory of your Next.js app with the n Add a [`open-next.config.ts`](https://opennext.js.org/aws/config) file to the root directory of your Next.js app: -```ts +```ts filename="open-next.config.ts" import type { OpenNextConfig } from "@opennextjs/aws/types/open-next.js"; import cache from "@opennextjs/cloudflare/kvCache"; @@ -123,7 +123,7 @@ export default config; 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: -```text +```plain filename=".dev.vars" NEXTJS_ENV=development ``` @@ -133,7 +133,7 @@ The `NEXTJS_ENV` variable defines the environment to use when loading Next.js `. Add the following to the scripts field of your `package.json` file: -```json +```json filename="package.json" "build:worker": "opennextjs-cloudflare", "dev:worker": "wrangler dev --port 8771", "preview": "npm run build:worker && npm run dev:worker", diff --git a/pages/cloudflare/former-releases/0.3/index.mdx b/pages/cloudflare/former-releases/0.3/index.mdx index b44423ed..d763ffc3 100644 --- a/pages/cloudflare/former-releases/0.3/index.mdx +++ b/pages/cloudflare/former-releases/0.3/index.mdx @@ -18,7 +18,7 @@ You can also use [`@cloudflare/next-on-pages`](https://www.npmjs.com/package/@cl To create a new Next.js app, pre-configured to run on Cloudflare using `@opennextjs/cloudflare`, run: -``` +```sh npm create cloudflare@latest -- my-next-app --framework=next --experimental ``` diff --git a/pages/cloudflare/former-releases/0.5/bindings.mdx b/pages/cloudflare/former-releases/0.5/bindings.mdx index df0a480a..a34c3b7c 100644 --- a/pages/cloudflare/former-releases/0.5/bindings.mdx +++ b/pages/cloudflare/former-releases/0.5/bindings.mdx @@ -45,7 +45,7 @@ Add bindings to your Worker by adding them to your [wrangler configuration file] To ensure that the `env` object from `getCloudflareContext().env` above has accurate TypeScript types, run the following Wrangler command to [generate types that match your Worker's configuration](https://developers.cloudflare.com/workers/languages/typescript/#generate-types-that-match-your-workers-configuration-experimental): -``` +```sh npx wrangler types --experimental-include-runtime ``` @@ -53,7 +53,7 @@ This will generate a `d.ts` file and (by default) save it to `.wrangler/types/ru If you would like to commit the file to git, you can provide a custom path. Here, for instance, the `runtime.d.ts` file will be saved to the root of your project: -```bash +```sh npx wrangler types --experimental-include-runtime="./runtime.d.ts" ``` diff --git a/pages/cloudflare/former-releases/0.5/caching.mdx b/pages/cloudflare/former-releases/0.5/caching.mdx index 738f24f0..74bc9546 100644 --- a/pages/cloudflare/former-releases/0.5/caching.mdx +++ b/pages/cloudflare/former-releases/0.5/caching.mdx @@ -21,7 +21,7 @@ The ISR adapter for Cloudflare uses [Workers KV](https://developers.cloudflare.c ##### 1. Create a KV namespace -``` +```sh npx wrangler@latest kv namespace create ``` @@ -29,8 +29,7 @@ npx wrangler@latest kv namespace create The binding name used in your app's worker is `NEXT_CACHE_WORKERS_KV`. The service binding should be a self reference to your worker where `` is the name in your wrangler configuration file. -```jsonc -// wrangler.jsonc +```jsonc filename="wrangler.jsonc" { // ... "kv_namespaces": [ @@ -59,8 +58,7 @@ The memory queue will send revalidation requests to a page when needed, and offe can use it at your own risk! -```ts -// open-next.config.ts +```ts filename="open-next.config.ts" import { defineCloudflareConfig } from "@opennextjs/cloudflare"; import kvIncrementalCache from "@opennextjs/cloudflare/kv-cache"; import memoryQueue from "@opennextjs/cloudflare/memory-queue"; @@ -90,8 +88,7 @@ To use on-demand revalidation, you should also follow the [ISR setup steps](#inc The binding name used in your app's worker is `NEXT_CACHE_D1`. The service binding should be a self reference to your worker where `` is the name in your wrangler configuration file. -```jsonc -// wrangler.jsonc +```jsonc filename="wrangler.jsonc" { // ... "d1_databases": [ @@ -129,8 +126,7 @@ wrangler d1 execute NEXT_CACHE_D1 --command "CREATE TABLE IF NOT EXISTS revalida In your project's OpenNext config, enable the KV cache and set up a queue. The queue will send a revalidation request to a page when needed, but it will not dedupe requests. -```ts -// open-next.config.ts +```ts filename="open-next.config.ts" import { defineCloudflareConfig } from "@opennextjs/cloudflare"; import kvIncrementalCache from "@opennextjs/cloudflare/kv-cache"; import d1TagCache from "@opennextjs/cloudflare/d1-tag-cache"; diff --git a/pages/cloudflare/former-releases/0.5/examples.mdx b/pages/cloudflare/former-releases/0.5/examples.mdx index e44bee0d..c156b6bb 100644 --- a/pages/cloudflare/former-releases/0.5/examples.mdx +++ b/pages/cloudflare/former-releases/0.5/examples.mdx @@ -4,7 +4,7 @@ import { Callout } from "nextra/components"; To create a new Next.js app, pre-configured to run on Cloudflare using `@opennextjs/cloudflare`, run: -``` +```sh npm create cloudflare@latest -- my-next-app --framework=next --experimental ``` diff --git a/pages/cloudflare/former-releases/0.5/get-started.mdx b/pages/cloudflare/former-releases/0.5/get-started.mdx index 10cb3189..83cfd8b3 100644 --- a/pages/cloudflare/former-releases/0.5/get-started.mdx +++ b/pages/cloudflare/former-releases/0.5/get-started.mdx @@ -44,7 +44,7 @@ application to be previewed and deployed, it is also where you configure your Wo You can create one yourself in the root directory of your Next.js app with the name `wrangler.jsonc` and the following content: -```jsonc +```jsonc filename="wrangler.jsonc" { "$schema": "node_modules/wrangler/config-schema.json", "main": ".open-next/worker.js", @@ -85,7 +85,7 @@ You can create one yourself in the root directory of your Next.js app with the n Add a [`open-next.config.ts`](https://opennext.js.org/aws/config) file to the root directory of your Next.js app: -```ts +```ts filename="open-next.config.ts" import { defineCloudflareConfig } from "@opennextjs/cloudflare"; import kvIncrementalCache from "@opennextjs/cloudflare/kv-cache"; @@ -103,7 +103,7 @@ export default defineCloudflareConfig({ 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: -```text +```plain filename=".dev.vars" NEXTJS_ENV=development ``` @@ -113,7 +113,7 @@ The `NEXTJS_ENV` variable defines the environment to use when loading Next.js `. Add the following to the scripts field of your `package.json` file: -```json +```json filename="package.json" "preview": "opennextjs-cloudflare && wrangler dev", "deploy": "opennextjs-cloudflare && wrangler deploy", "cf-typegen": "wrangler types --env-interface CloudflareEnv cloudflare-env.d.ts", @@ -160,8 +160,7 @@ from the `@opennextjs/cloudflare` package. This makes sure that the Next.js dev This is an example of a Next.js configuration file calling the utility: -```ts -// next.config.ts +```ts filename="next.config.ts" import type { NextConfig } from "next"; const nextConfig: NextConfig = { diff --git a/pages/cloudflare/former-releases/0.5/index.mdx b/pages/cloudflare/former-releases/0.5/index.mdx index cdb70bb8..c7d3b898 100644 --- a/pages/cloudflare/former-releases/0.5/index.mdx +++ b/pages/cloudflare/former-releases/0.5/index.mdx @@ -18,7 +18,7 @@ You can also use [`@cloudflare/next-on-pages`](https://www.npmjs.com/package/@cl To create a new Next.js app, pre-configured to run on Cloudflare using `@opennextjs/cloudflare`, run: -``` +```sh npm create cloudflare@latest -- my-next-app --framework=next --experimental ``` diff --git a/pages/cloudflare/former-releases/0.6/bindings.mdx b/pages/cloudflare/former-releases/0.6/bindings.mdx index df0a480a..a34c3b7c 100644 --- a/pages/cloudflare/former-releases/0.6/bindings.mdx +++ b/pages/cloudflare/former-releases/0.6/bindings.mdx @@ -45,7 +45,7 @@ Add bindings to your Worker by adding them to your [wrangler configuration file] To ensure that the `env` object from `getCloudflareContext().env` above has accurate TypeScript types, run the following Wrangler command to [generate types that match your Worker's configuration](https://developers.cloudflare.com/workers/languages/typescript/#generate-types-that-match-your-workers-configuration-experimental): -``` +```sh npx wrangler types --experimental-include-runtime ``` @@ -53,7 +53,7 @@ This will generate a `d.ts` file and (by default) save it to `.wrangler/types/ru If you would like to commit the file to git, you can provide a custom path. Here, for instance, the `runtime.d.ts` file will be saved to the root of your project: -```bash +```sh npx wrangler types --experimental-include-runtime="./runtime.d.ts" ``` diff --git a/pages/cloudflare/former-releases/0.6/caching.mdx b/pages/cloudflare/former-releases/0.6/caching.mdx index 47e94eb8..aee51a9e 100644 --- a/pages/cloudflare/former-releases/0.6/caching.mdx +++ b/pages/cloudflare/former-releases/0.6/caching.mdx @@ -25,7 +25,7 @@ There are two storage options to use for the incremental cache. ##### 1. Create a KV namespace -``` +```sh npx wrangler@latest kv namespace create ``` @@ -34,8 +34,7 @@ npx wrangler@latest kv namespace create The binding name used in your app's worker is `NEXT_INC_CACHE_KV`. The `WORKER_SELF_REFERENCE` service binding should be a self reference to your worker where `` is the name in your wrangler configuration file. -```jsonc -// wrangler.jsonc +```jsonc filename="wrangler.jsonc" { // ... "name": "", @@ -58,8 +57,7 @@ The `WORKER_SELF_REFERENCE` service binding should be a self reference to your w In your project's OpenNext config, enable the KV cache. -```ts -// open-next.config.ts +```ts filename="open-next.config.ts" import { defineCloudflareConfig } from "@opennextjs/cloudflare"; import kvIncrementalCache from "@opennextjs/cloudflare/overrides/incremental-cache/kv-incremental-cache"; // ... @@ -76,7 +74,7 @@ export default defineCloudflareConfig({ ##### 1. Create an R2 Bucket -``` +```sh npx wrangler@latest r2 bucket create ``` @@ -86,8 +84,7 @@ The binding name used in your app's worker is `NEXT_INC_CACHE_R2_BUCKET`. The se The prefix used by the R2 bucket can be configured with the `NEXT_INC_CACHE_R2_PREFIX` environment variable, and defaults to `incremental-cache`. -```jsonc -// wrangler.jsonc +```jsonc filename="wrangler.jsonc" { // ... "name": "", @@ -120,8 +117,7 @@ The regional cache has two modes: Additionally, lazy updating of the regional cache can be enabled with the `shouldLazilyUpdateOnCacheHit` option. When requesting data from the cache, it sends a background request to the R2 bucket to get the latest entry. This is enabled by default for the `long-lived` mode. -```ts -// open-next.config.ts +```ts filename="open-next.config.ts" import { defineCloudflareConfig } from "@opennextjs/cloudflare"; import r2IncrementalCache from "@opennextjs/cloudflare/overrides/incremental-cache/r2-incremental-cache"; import { withRegionalCache } from "@opennextjs/cloudflare/overrides/incremental-cache/regional-cache"; @@ -153,8 +149,7 @@ In your project's OpenNext config, enable the cache and set up a queue. The Durable Object Queue will send revalidation requests to a page when needed, and offers support for de-duplicating requests. By default there will be a maximum of 10 instance of the Durables Object Queue and they can each process up to 5 requests in parallel, for up to 50 concurrent ISR revalidations. -```ts -// open-next.config.ts +```ts filename="open-next.config.ts" import { defineCloudflareConfig } from "@opennextjs/cloudflare"; // ... import doQueue from "@opennextjs/cloudflare/overrides/queue/do-queue"; @@ -167,7 +162,7 @@ export default defineCloudflareConfig({ You will also need to add some binding to your `wrangler.jsonc` file. -```jsonc +```jsonc filename="wrangler.jsonc" "durable_objects": { "bindings": [ { @@ -230,8 +225,7 @@ If either of these factors is significant, opting for a sharded database is reco The binding name used in your app's worker is `NEXT_TAG_CACHE_D1`. The `WORKER_SELF_REFERENCE` service binding should be a self reference to your worker where `` is the name in your wrangler configuration file. -```jsonc -// wrangler.jsonc +```jsonc filename="wrangler.jsonc" { // ... "d1_databases": [ @@ -258,8 +252,7 @@ The D1 tag cache requires a `revalidations` table that tracks On-Demand revalida In your project's OpenNext config, enable the KV cache and set up a queue (see above). The queue will send a revalidation request to a page when needed, but it will not dedupe requests. -```ts -// open-next.config.ts +```ts filename="open-next.config.ts" import { defineCloudflareConfig } from "@opennextjs/cloudflare"; import kvIncrementalCache from "@opennextjs/cloudflare/kv-cache"; import d1NextTagCache from "@opennextjs/cloudflare/d1-next-tag-cache"; @@ -278,8 +271,7 @@ export default defineCloudflareConfig({ ##### 1. Create a Durable Object and Service Binding The service binding should be a self reference to your worker where `` is the name in your wrangler configuration file. -```jsonc -// wrangler.jsonc +```jsonc filename="wrangler.jsonc" { // ... "durable_objects": { @@ -313,8 +305,7 @@ The service binding should be a self reference to your worker where `` is the name in your wrangler configuration file. -```jsonc -// wrangler.jsonc +```jsonc filename="wrangler.jsonc" { // ... "name": "", @@ -379,8 +369,7 @@ The D1 database uses two tables, created when initialising the cache: In your project's OpenNext config, enable the KV cache and set up a queue. The queue will send a revalidation request to a page when needed, but it will not dedupe requests. -```ts -// open-next.config.ts +```ts filename="open-next.config.ts" import { defineCloudflareConfig } from "@opennextjs/cloudflare"; import kvIncrementalCache from "@opennextjs/cloudflare/overrides/incremental-cache/kv-incremental-cache"; import d1TagCache from "@opennextjs/cloudflare/overrides/tag-cache/d1-tag-cache"; diff --git a/pages/cloudflare/former-releases/0.6/examples.mdx b/pages/cloudflare/former-releases/0.6/examples.mdx index e44bee0d..c156b6bb 100644 --- a/pages/cloudflare/former-releases/0.6/examples.mdx +++ b/pages/cloudflare/former-releases/0.6/examples.mdx @@ -4,7 +4,7 @@ import { Callout } from "nextra/components"; To create a new Next.js app, pre-configured to run on Cloudflare using `@opennextjs/cloudflare`, run: -``` +```sh npm create cloudflare@latest -- my-next-app --framework=next --experimental ``` diff --git a/pages/cloudflare/former-releases/0.6/get-started.mdx b/pages/cloudflare/former-releases/0.6/get-started.mdx index 833f25b5..716b8539 100644 --- a/pages/cloudflare/former-releases/0.6/get-started.mdx +++ b/pages/cloudflare/former-releases/0.6/get-started.mdx @@ -44,7 +44,7 @@ application to be previewed and deployed, it is also where you configure your Wo You can create one yourself in the root directory of your Next.js app with the name `wrangler.jsonc` and the following content: -```jsonc +```jsonc filename="wrangler.jsonc" { "$schema": "node_modules/wrangler/config-schema.json", "main": ".open-next/worker.js", @@ -92,7 +92,7 @@ You can create one yourself in the root directory of your Next.js app with the n Add a [`open-next.config.ts`](https://opennext.js.org/aws/config) file to the root directory of your Next.js app: -```ts +```ts filename="open-next.config.ts" import { defineCloudflareConfig } from "@opennextjs/cloudflare"; import kvIncrementalCache from "@opennextjs/cloudflare/overrides/incremental-cache/kv-incremental-cache"; @@ -110,7 +110,7 @@ export default defineCloudflareConfig({ 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: -```text +```plain filename=".dev.vars" NEXTJS_ENV=development ``` @@ -120,7 +120,7 @@ The `NEXTJS_ENV` variable defines the environment to use when loading Next.js `. Add the following to the scripts field of your `package.json` file: -```json +```json filename="package.json" "preview": "opennextjs-cloudflare build && opennextjs-cloudflare preview", "deploy": "opennextjs-cloudflare build && opennextjs-cloudflare deploy", "cf-typegen": "wrangler types --env-interface CloudflareEnv cloudflare-env.d.ts", @@ -167,8 +167,7 @@ from the `@opennextjs/cloudflare` package. This makes sure that the Next.js dev This is an example of a Next.js configuration file calling the utility: -```ts -// next.config.ts +```ts filename="next.config.ts" import type { NextConfig } from "next"; const nextConfig: NextConfig = { diff --git a/pages/cloudflare/former-releases/migrate-from-0.2-to-0.3.mdx b/pages/cloudflare/former-releases/migrate-from-0.2-to-0.3.mdx index e213c6f4..3798f452 100644 --- a/pages/cloudflare/former-releases/migrate-from-0.2-to-0.3.mdx +++ b/pages/cloudflare/former-releases/migrate-from-0.2-to-0.3.mdx @@ -10,7 +10,7 @@ You will need to update your projects based on the 0.2 release as described in t The entry point is now `.open-next/worker.js`, update `wrangler.toml` accordingly: -```toml +```toml filename="wrangler.toml" # CHANGED: new entry point location main = ".open-next/worker.js" name = "my-app" @@ -27,7 +27,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 +```ts filename="open-next.config.ts" import type { OpenNextConfig } from "@opennextjs/aws/types/open-next.js"; import cache from "@opennextjs/cloudflare/kvCache"; @@ -62,7 +62,7 @@ You can either install the `@opennextjs/aws` NPM package to get the types or `op 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: -```text +```plain filename=".dev.vars" NEXTJS_ENV=development ``` @@ -72,8 +72,10 @@ The `NEXTJS_ENV` variable defines the environment to use when loading Next.js `. The name of the CLI was changed to `opennextjs-cloudflare`: -```json -"build:worker": "opennextjs-cloudflare", +```json filename="package.json" +{ + "build:worker": "opennextjs-cloudflare" +} ``` ##### 5 Add `.open-next` to `.gitignore` diff --git a/pages/cloudflare/former-releases/migrate-from-0.3-to-0.4.mdx b/pages/cloudflare/former-releases/migrate-from-0.3-to-0.4.mdx index 70fb3647..32d592ad 100644 --- a/pages/cloudflare/former-releases/migrate-from-0.3-to-0.4.mdx +++ b/pages/cloudflare/former-releases/migrate-from-0.3-to-0.4.mdx @@ -13,9 +13,7 @@ configuration file to import and call the utility. Example: -```js -// next.config.mjs - +```js filename="next.config.mjs" import { initOpenNextCloudflareForDev } from "@opennextjs/cloudflare"; initOpenNextCloudflareForDev(); diff --git a/pages/cloudflare/former-releases/migrate-from-0.5-to-0.6.mdx b/pages/cloudflare/former-releases/migrate-from-0.5-to-0.6.mdx index be0285f8..d154efdb 100644 --- a/pages/cloudflare/former-releases/migrate-from-0.5-to-0.6.mdx +++ b/pages/cloudflare/former-releases/migrate-from-0.5-to-0.6.mdx @@ -41,7 +41,9 @@ The CLI was previsouly invoked as `opennextjs-cloudflare` and now takes a mandat You will need to update the `scripts` in your `package.json`: -```json -"preview": "opennextjs-cloudflare build && opennextjs-cloudflare preview", -"deploy": "opennextjs-cloudflare build && opennextjs-cloudflare deploy", +```json filename="package.json" +{ + "preview": "opennextjs-cloudflare build && opennextjs-cloudflare preview", + "deploy": "opennextjs-cloudflare build && opennextjs-cloudflare deploy" +} ``` diff --git a/pages/cloudflare/get-started.mdx b/pages/cloudflare/get-started.mdx index 92ce105e..9ef4fb95 100644 --- a/pages/cloudflare/get-started.mdx +++ b/pages/cloudflare/get-started.mdx @@ -54,7 +54,7 @@ application to be previewed and deployed, it is also where you configure your Wo You can create one yourself in the root directory of your Next.js app with the name `wrangler.jsonc` and the following content: -```jsonc +```jsonc filename="wrangler.jsonc" { "$schema": "node_modules/wrangler/config-schema.json", "main": ".open-next/worker.js", @@ -113,7 +113,7 @@ You can create one yourself in the root directory of your Next.js app with the n Add a [`open-next.config.ts`](https://opennext.js.org/aws/config) file to the root directory of your Next.js app: -```ts +```ts filename="open-next.config.ts" import { defineCloudflareConfig } from "@opennextjs/cloudflare"; import r2IncrementalCache from "@opennextjs/cloudflare/overrides/incremental-cache/r2-incremental-cache"; @@ -131,7 +131,7 @@ export default defineCloudflareConfig({ 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: -```text +```plain filename=".dev.vars" NEXTJS_ENV=development ``` @@ -141,12 +141,14 @@ The `NEXTJS_ENV` variable defines the environment to use when loading Next.js `. Add the following to the scripts field of your `package.json` file: -```json -"build": "next build", -"preview": "opennextjs-cloudflare build && opennextjs-cloudflare preview", -"deploy": "opennextjs-cloudflare build && opennextjs-cloudflare deploy", -"upload": "opennextjs-cloudflare build && opennextjs-cloudflare upload", -"cf-typegen": "wrangler types --env-interface CloudflareEnv cloudflare-env.d.ts", +```json filename="package.json" +{ + "build": "next build", + "preview": "opennextjs-cloudflare build && opennextjs-cloudflare preview", + "deploy": "opennextjs-cloudflare build && opennextjs-cloudflare deploy", + "upload": "opennextjs-cloudflare build && opennextjs-cloudflare upload", + "cf-typegen": "wrangler types --env-interface CloudflareEnv cloudflare-env.d.ts" +} ``` - The `build` script must invoke the Next.js build command, it will be invoked by [`opennextjs-cloudflare build`](/cloudflare/cli#build-command). @@ -159,7 +161,7 @@ Add the following to the scripts field of your `package.json` file: Add a `public/_headers` file, with at least the following headers: -```txt +```plain filename="public/_headers" /_next/static/* Cache-Control: public,max-age=31536000,immutable ``` @@ -203,8 +205,7 @@ from the `@opennextjs/cloudflare` package. This makes sure that the Next.js dev This is an example of a Next.js configuration file calling the utility: -```ts -// next.config.ts +```ts filename="next.config.ts" import type { NextConfig } from "next"; const nextConfig: NextConfig = { diff --git a/pages/cloudflare/howtos/assets.mdx b/pages/cloudflare/howtos/assets.mdx index e3c09e1b..4fd01511 100644 --- a/pages/cloudflare/howtos/assets.mdx +++ b/pages/cloudflare/howtos/assets.mdx @@ -12,8 +12,7 @@ Note that `run_worker_first` could also be set to a list of patterns - this is a When `run_worker_first` is set to `false`, requests are intercepted before reaching the worker and are not billed: -```jsonc -// wrangler.jsonc +```jsonc filename="wrangler.jsonc" { "name": "my-app", // ... @@ -35,8 +34,7 @@ When `run_worker_first=false` you can still configure [headers](https://develope When `run_worker_first` is set to `true`, all the requests will reach the Worker and be billed: -```jsonc -// wrangler.jsonc +```jsonc filename="wrangler.jsonc" { "name": "my-app", // ... diff --git a/pages/cloudflare/howtos/custom-worker.mdx b/pages/cloudflare/howtos/custom-worker.mdx index cab9ea98..e3f34b6a 100644 --- a/pages/cloudflare/howtos/custom-worker.mdx +++ b/pages/cloudflare/howtos/custom-worker.mdx @@ -10,9 +10,7 @@ The custom worker re-uses the generated fetch handler. The following custom worker re-uses the generated fetch handler and adds a scheduled handler: -```ts -// custom-worker.ts - +```ts filename="custom-worker.ts" // @ts-ignore `.open-next/worker.ts` is generated at build time import { default as handler } from "./.open-next/worker.js"; @@ -34,8 +32,7 @@ See [an example in the adapter repository](https://github.com/opennextjs/opennex ### Update the entry point in your wrangler configuration -```diff -// wrangler.jsonc +```diff filename="wrangler.jsonc" { - "main": "./.open-next/worker.js" + "main": "./path/to/custom-worker.ts", diff --git a/pages/cloudflare/howtos/db.mdx b/pages/cloudflare/howtos/db.mdx index 4a8a781b..0c2ab96a 100644 --- a/pages/cloudflare/howtos/db.mdx +++ b/pages/cloudflare/howtos/db.mdx @@ -15,8 +15,7 @@ Instead of creating a global client, you should create a new client for each req Instead of that : -```ts -//lib/db.ts +```ts filename="lib/db.ts" import { drizzle } from "drizzle-orm/node-postgres"; import * as schema from "./schema/pg"; import { Pool } from "pg"; @@ -30,8 +29,7 @@ export const db = drizzle({ client: pool, schema }); You should do this instead: -```ts -//lib/db.ts +```ts filename="lib/db.ts" import { drizzle } from "drizzle-orm/node-postgres"; // You can use cache from react to cache the client during the same request // this is not mandatory and only has an effect for server components @@ -51,7 +49,7 @@ export const getDb = cache(() => { #### D1 example -```ts +```ts filename="lib/db.ts" import { getCloudflareContext } from "@opennextjs/cloudflare"; import { drizzle } from "drizzle-orm/d1"; import { cache } from "react"; @@ -71,7 +69,7 @@ export const getDbAsync = cache(async () => { #### Hyperdrive example -```ts +```ts filename="lib/db.ts" import { getCloudflareContext } from "@opennextjs/cloudflare"; import { drizzle } from "drizzle-orm/node-postgres"; import { cache } from "react"; @@ -112,7 +110,7 @@ You can then use the `getDb` function to get a new client for each request. This When using prisma in OpenNext, you do not want to provide an output directory for the generated client. -```prisma +```prisma filename="schema.prisma" generator client { provider = "prisma-client-js" previewFeatures = ["driverAdapters"] @@ -125,7 +123,7 @@ This is because the generated client needs to be patched by OpenNext to work wit Because prisma has some specific exports for cloudflare workers, you need to add the following to your `next.config.ts` file: -```ts +```ts filename="next.config.ts" const nextConfig: NextConfig = { serverExternalPackages: ["@prisma/client", ".prisma/client"], }; @@ -141,8 +139,7 @@ Instead of creating a global client, you should create a new client for each req Instead of that : -```ts -//lib/db.ts +```ts filename="lib/db.ts" import { getCloudflareContext } from "@opennextjs/cloudflare"; import { PrismaClient } from "@prisma/client"; import { PrismaD1 } from "@prisma/adapter-d1"; @@ -154,8 +151,7 @@ export const db = new PrismaClient(); You should do this instead: -```ts -//lib/db.ts +```ts filename="lib/db.ts" import { getCloudflareContext } from "@opennextjs/cloudflare"; // You can use cache from react to cache the client during the same request // this is not mandatory and only has an effect for server components @@ -184,7 +180,7 @@ You can then use the `getDb` function to get a new client for each request. This You can also use Prisma with PostgreSQL. The setup is similar to the D1 setup above, but you need to use the `PrismaPostgres` adapter instead of the `PrismaD1` adapter. -```ts +```ts filename="lib/db.ts" import { cache } from "react"; import { PrismaClient } from "@prisma/client"; import { PrismaPg } from "@prisma/adapter-pg"; @@ -203,8 +199,7 @@ You can then use the `getDb` function to get a new client for each request. This You can also use Prisma with Hyperdrive. The setup is similar to the PostgreSQL setup above. -```ts -//lib/db.ts +```ts filename="lib/db.ts" import { getCloudflareContext } from "@opennextjs/cloudflare"; // You can use cache from react to cache the client during the same request // this is not mandatory and only has an effect for server components diff --git a/pages/cloudflare/howtos/dev-deploy.mdx b/pages/cloudflare/howtos/dev-deploy.mdx index c655ccc3..8e5b73a4 100644 --- a/pages/cloudflare/howtos/dev-deploy.mdx +++ b/pages/cloudflare/howtos/dev-deploy.mdx @@ -16,7 +16,7 @@ Let's explore, in more detail, the application development workflow we recommend To create a new Next.js app, pre-configured to run on Cloudflare using `@opennextjs/cloudflare`, run: -```bash +```sh npm create cloudflare@latest -- my-next-app --framework=next --platform=workers ``` @@ -26,8 +26,7 @@ We believe that the best development workflow uses the `next dev` command provid To access Cloudflare resources using the `getCloudflareContext` API while running `next dev`, you will need to update the Next.js configuration to call `initOpenNextCloudflareForDev`, as shown in the following example: -```ts -// next.config.ts +```ts filename="next.config.ts" import type { NextConfig } from "next"; const nextConfig: NextConfig = { diff --git a/pages/cloudflare/howtos/env-vars.mdx b/pages/cloudflare/howtos/env-vars.mdx index b4877fdc..1ead2703 100644 --- a/pages/cloudflare/howtos/env-vars.mdx +++ b/pages/cloudflare/howtos/env-vars.mdx @@ -16,8 +16,7 @@ Next.js `.env` files are environment specific. That is a `.env.development` will You should use the `NEXTJS_ENV` environment variable to select the environment to use when running your app locally on a worker, that's how you would select the "development" environment: -```plain -# .dev.vars +```plain filename=".dev.vars" NEXTJS_ENV=development ``` diff --git a/pages/cloudflare/howtos/image.mdx b/pages/cloudflare/howtos/image.mdx index a11931ae..df994918 100644 --- a/pages/cloudflare/howtos/image.mdx +++ b/pages/cloudflare/howtos/image.mdx @@ -10,8 +10,7 @@ The Cloudflare adapter provides a Next.js-compatible image optimization API usin The `IMAGES` binding must be defined to enable image optimization: -```jsonc -// wrangler.jsonc +```jsonc filename="wrangler.jsonc" { "images": { "binding": "IMAGES", @@ -37,8 +36,7 @@ You then need to configure your Next application to use a custom loader for Clou Create an `image-loader.ts` at the root of your application: -```ts -// image-loader.ts +```ts filename="image-loader.ts" import type { ImageLoaderProps } from "next/image"; const normalizeSrc = (src: string) => { @@ -67,8 +65,7 @@ export default function cloudflareLoader({ src, width, quality }: ImageLoaderPro You will then need to update your app configuration to use this loader: -```ts -// next.config.ts +```ts filename="next.config.ts" import type { NextConfig } from "next"; const nextConfig: NextConfig = { diff --git a/pages/cloudflare/howtos/keep_names.mdx b/pages/cloudflare/howtos/keep_names.mdx index 947f94ef..17d92696 100644 --- a/pages/cloudflare/howtos/keep_names.mdx +++ b/pages/cloudflare/howtos/keep_names.mdx @@ -9,7 +9,7 @@ to strings. This happens because `esbuild` introduces a `__name` function at the in the generated script strings. When these strings are evaluated at runtime, the `__name` function might therefore not be defined, leading to errors logged in the developer console: -``` +```plain Uncaught ReferenceError: __name is not defined ``` @@ -22,7 +22,7 @@ Uncaught ReferenceError: __name is not defined To fix the issue you can simply set the `keep_names` option to `false` in your [`wrangler.jsonc` file](https://developers.cloudflare.com/workers/wrangler/configuration), like in the following example: -```jsonc +```jsonc filename="wrangler.jsonc" { "$schema": "node_modules/wrangler/config-schema.json", "main": ".open-next/worker.js", diff --git a/pages/cloudflare/howtos/multi-worker.mdx b/pages/cloudflare/howtos/multi-worker.mdx index e7964d2a..9c3e2ba6 100644 --- a/pages/cloudflare/howtos/multi-worker.mdx +++ b/pages/cloudflare/howtos/multi-worker.mdx @@ -30,7 +30,7 @@ This multi-worker approach is beneficial when you need: Here we assume a configuration like that: -```ts +```ts filename="open-next.config.ts" import { defineCloudflareConfig } from "@opennextjs/cloudflare"; import r2IncrementalCache from "@opennextjs/cloudflare/overrides/incremental-cache/r2-incremental-cache"; import { withRegionalCache } from "@opennextjs/cloudflare/overrides/incremental-cache/regional-cache"; @@ -65,11 +65,11 @@ export default defineCloudflareConfig({ You'll need 2 custom workers in order for this to work: -```js -// middleware.js +```js filename="middleware.js" import { WorkerEntrypoint } from "cloudflare:workers"; +``` -// ./.open-next/cloudflare/init.js +```js filename="/.open-next/cloudflare/init.js" import { runWithCloudflareRequestContext } from "./.open-next/cloudflare/init.js"; import { handler as middlewareHandler } from "./.open-next/middleware/handler.mjs"; @@ -107,9 +107,7 @@ export default class extends WorkerEntrypoint { } ``` -```js -// server.js - +```js filename="server.js" // Replace with your actual build output directory, typically: // ./.open-next/cloudflare/init.js import { runWithCloudflareRequestContext } from "./.open-next/cloudflare/init.js"; @@ -128,7 +126,7 @@ export default { ### Wrangler configurations -```jsonc +```jsonc filename="wrangler.jsonc" // Middleware wrangler file { "main": "middleware.js", @@ -184,7 +182,7 @@ export default { } ``` -```jsonc +```jsonc filename="wrangler.jsonc" // Server wrangler file { "main": "server.js", diff --git a/pages/cloudflare/howtos/skew.mdx b/pages/cloudflare/howtos/skew.mdx index d13895a0..36c5f166 100644 --- a/pages/cloudflare/howtos/skew.mdx +++ b/pages/cloudflare/howtos/skew.mdx @@ -16,8 +16,7 @@ The Cloudflare adapter has _experimental support_ for skew protection based on [ Set `cloudflare.skewProtection.enabled` to `true` to enable skew protection: -```ts -// open-next.config.ts +```ts filename="open-next.config.ts" export default { // ... cloudflare: { @@ -38,8 +37,7 @@ export default { The Worker needs to serve the correct version of the app assets. For that it need be be executed before incoming requests are matched against the assets. Set [`run_worker_first`](https://developers.cloudflare.com/workers/static-assets/binding/#run_worker_first) to `true` in your wrangler configuration to enable this behavior: -```jsonc -// wrangler.jsonc +```jsonc filename="wrangler.jsonc" { "name": "my-app", // ... @@ -72,11 +70,11 @@ You must set a different `deploymentId` in your next config each time your app i The cloudflare adapter exports a `getDeploymentId()` function that can be used to generate a unique deployment id. -```ts -// next.config.ts +```ts filename="next.config.ts" +import type { NextConfig } from "next"; import { getDeploymentId } from "@opennextjs/cloudflare"; -const nextConfig = { +const nextConfig: NextConfig = { // ... deploymentId: getDeploymentId(), }; diff --git a/pages/cloudflare/howtos/workerd.mdx b/pages/cloudflare/howtos/workerd.mdx index 2694c627..35aeb15b 100644 --- a/pages/cloudflare/howtos/workerd.mdx +++ b/pages/cloudflare/howtos/workerd.mdx @@ -7,7 +7,7 @@ While the [`nodejs_compat`](https://developers.cloudflare.com/workers/configuration/compatibility-flags/#nodejs-compatibility-flag) flag makes `workerd` mostly compatible with Node.js, there are still minor differences. Some packages publish code for different runtimes to account for those differences. For example, `postgres` has [conditional exports](https://nodejs.org/api/packages.html#conditional-exports) in its [`package.json`](https://github.com/porsager/postgres/blob/ad0ed4476e09f41f147859cb5a42971d2b99e9c7/package.json#L8-L13): -```json +```json filename="package.json" "exports": { "types": "./types/index.d.ts", "bun": "./src/index.js", @@ -24,8 +24,7 @@ For that, you need to instruct Next.js not to bundle packages as it would use th To do that, add those packages in the `serverExternalPackages` key of your `next.config.ts`: -```ts -// node.config.ts +```ts filename="next.config.ts" import type { NextConfig } from "next"; const nextConfig: NextConfig = { diff --git a/pages/cloudflare/index.mdx b/pages/cloudflare/index.mdx index 4073d0fc..3c93a3af 100644 --- a/pages/cloudflare/index.mdx +++ b/pages/cloudflare/index.mdx @@ -11,7 +11,7 @@ The [`@opennextjs/cloudflare`](https://www.npmjs.com/package/@opennextjs/cloudfl To create a new Next.js app, pre-configured to run on Cloudflare using `@opennextjs/cloudflare`, run: -``` +```sh npm create cloudflare@latest -- my-next-app --framework=next --platform=workers ``` @@ -67,7 +67,7 @@ You can view the code for `@opennextjs/cloudflare` [here](https://github.com/ope The size limit of a Cloudflare Worker is 3 MiB on the Workers Free plan, and 10 MiB on the Workers Paid plan. After building your Worker, `wrangler` will show both the original and compressed sizes: -``` +```plain Total Upload: 13833.20 KiB / gzip: 2295.89 KiB ``` diff --git a/pages/cloudflare/perf.mdx b/pages/cloudflare/perf.mdx index d6703925..89ec921c 100644 --- a/pages/cloudflare/perf.mdx +++ b/pages/cloudflare/perf.mdx @@ -62,9 +62,7 @@ You can profile the code to troubleshoot performance issues. Code profiles are much easier to read when the code is not minified, you can use the following settings to generate unminified code -**next.config.ts** - -```ts +```ts filename="next.config.ts" const nextConfig = { // ... experimental: { @@ -81,7 +79,7 @@ const nextConfig = { Use the `--noMinify` option when building the app: -```bash +```sh opennextjs-cloudflare build --noMinify ``` @@ -89,7 +87,7 @@ opennextjs-cloudflare build --noMinify You should first launch a local version of your application by running -```bash +```sh opennextjs-cloudflare preview ``` diff --git a/pages/cloudflare/troubleshooting.mdx b/pages/cloudflare/troubleshooting.mdx index 702f6fbf..78b80314 100644 --- a/pages/cloudflare/troubleshooting.mdx +++ b/pages/cloudflare/troubleshooting.mdx @@ -23,7 +23,7 @@ Refer to the [Node.js Workers docs](https://developers.cloudflare.com/workers/ru Some NPM packages define multiple exports. For example: -``` +```json filename="package.json" "exports": { "other": "./src/other.js", "node": "./src/node.js", @@ -36,7 +36,7 @@ When you use `@opennextjs/cloudflare`, [Wrangler](https://developers.cloudflare. You may want to modify how Wrangler resolves multiple exports, such that when you import packages, the `node` export, if present, is used. You can do do by defining the following variables in a `.env` file within the root directory of your Next.js app: -``` +```plain filename=".env" WRANGLER_BUILD_CONDITIONS="" WRANGLER_BUILD_PLATFORM="node" ``` @@ -56,15 +56,15 @@ To solve this, you should create the DB client inside a request context and not A global client would not work: -```ts -// src/lib/db.ts +```ts filename="src/lib/db.ts" import postgres from "postgres"; // `client` is global. // As the connection would be shared across requests, it fails on worker export const client = postgres(process.env.DATABASE_URL, { max: 5 }); +``` -// src/app/api/route.ts +```ts filename="src/app/api/route.ts" import { client } from "@/db/db"; export const dynamic = "force-dynamic"; @@ -76,8 +76,7 @@ export async function GET() { It can fixed by creating the client for each incoming request: -```ts -// src/app/api/route.ts +```ts filename="src/app/api/route.ts" export const dynamic = "force-dynamic"; export async function GET() { @@ -129,7 +128,7 @@ This error occurs because the `FinalizationRegistry` API is not available in old To fix this issue, update your `compatibility_date` in `wrangler.toml` or `wrangler.jsonc` to `2025-05-05` or later: -```json +```jsonc filename="wrangler.jsonc" { "compatibility_date": "2025-05-05" } diff --git a/pages/netlify/index.mdx b/pages/netlify/index.mdx index 91c546a7..f289757b 100644 --- a/pages/netlify/index.mdx +++ b/pages/netlify/index.mdx @@ -80,7 +80,7 @@ If you’re planning to use pnpm with Next.js to manage dependencies, you must d - Set a `PNPM_FLAGS` [environment variable](https://docs.netlify.com/environment-variables/get-started/#create-environment-variables) with a value of `--shamefully-hoist`. This appends a `--shamefully-hoist` argument to the `pnpm install` command that Netlify runs. - [Enable public hoisting](https://pnpm.io/npmrc#public-hoist-pattern) by adding an `.npmrc` file in the root of your project with this content: - ```bash + ```sh public-hoist-pattern[]=* ``` From fe17ae61af710d2e0b9b214cef510d5d893d5992 Mon Sep 17 00:00:00 2001 From: Akihiro Nagai <77012577+314systems@users.noreply.github.com> Date: Mon, 27 Apr 2026 21:00:50 +0900 Subject: [PATCH 2/6] prettier --- pages/aws/config/nx.mdx | 10 +++++----- pages/aws/v2/advanced/debugging.mdx | 2 +- pages/cloudflare/caching.mdx | 10 +++++----- pages/cloudflare/troubleshooting.mdx | 2 +- 4 files changed, 12 insertions(+), 12 deletions(-) diff --git a/pages/aws/config/nx.mdx b/pages/aws/config/nx.mdx index 616f377f..c87e279f 100644 --- a/pages/aws/config/nx.mdx +++ b/pages/aws/config/nx.mdx @@ -40,14 +40,14 @@ module.exports = composePlugins(...plugins)(nextConfig); 3. Create `open-next.config.ts` inside your apps root directory, it should look a little something like this: ```ts filename="open-next.config.ts" -import type { OpenNextConfig } from '@opennextjs/aws/types/open-next'; +import type { OpenNextConfig } from "@opennextjs/aws/types/open-next"; const config = { default: {}, - buildCommand: 'exit 0', // in my example we set up Nx task distribution to handle the order of building. - buildOutputPath: '.', - appPath: '.', - packageJsonPath: '../../', // again, path to the root of your repo (where the package.json is) + buildCommand: "exit 0", // in my example we set up Nx task distribution to handle the order of building. + buildOutputPath: ".", + appPath: ".", + packageJsonPath: "../../", // again, path to the root of your repo (where the package.json is) } satisfies OpenNextConfig; export default config; diff --git a/pages/aws/v2/advanced/debugging.mdx b/pages/aws/v2/advanced/debugging.mdx index fd08987d..3f6c77c6 100644 --- a/pages/aws/v2/advanced/debugging.mdx +++ b/pages/aws/v2/advanced/debugging.mdx @@ -9,7 +9,7 @@ If the server function is **deployed to Lambda@Edge**, the logs will appear in t The logs from the warmer function provide insights into the results of the warming process. ```json -{ event: 'warmer result', sent: 2, success: 2, uniqueServersWarmed: 2 } +{ "event": "warmer result", "sent": 2, "success": 2, "uniqueServersWarmed": 2 } ``` - `sent` — The number of times the warmer invoked the server function using the Lambda SDK. This value should correspond to the `CONCURRENCY` set in the warmer function. diff --git a/pages/cloudflare/caching.mdx b/pages/cloudflare/caching.mdx index 9b7f402c..2009bd80 100644 --- a/pages/cloudflare/caching.mdx +++ b/pages/cloudflare/caching.mdx @@ -455,15 +455,15 @@ You will also need to add some binding to your `wrangler.jsonc` file. "bindings": [ { "name": "NEXT_CACHE_DO_QUEUE", - "class_name": "DOQueueHandler" - } - ] + "class_name": "DOQueueHandler", + }, + ], }, "migrations": [ { "tag": "v1", - "new_sqlite_classes": ["DOQueueHandler"] - } + "new_sqlite_classes": ["DOQueueHandler"], + }, ], } ``` diff --git a/pages/cloudflare/troubleshooting.mdx b/pages/cloudflare/troubleshooting.mdx index 78b80314..05231842 100644 --- a/pages/cloudflare/troubleshooting.mdx +++ b/pages/cloudflare/troubleshooting.mdx @@ -130,7 +130,7 @@ To fix this issue, update your `compatibility_date` in `wrangler.toml` or `wrang ```jsonc filename="wrangler.jsonc" { - "compatibility_date": "2025-05-05" + "compatibility_date": "2025-05-05", } ``` From 111e8e4285c202b3f804df2150e80f61ca9b61da Mon Sep 17 00:00:00 2001 From: Victor Berchet Date: Mon, 27 Apr 2026 17:36:21 +0200 Subject: [PATCH 3/6] Apply suggestion from @vicb --- pages/aws/inner_workings/components/middleware.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/aws/inner_workings/components/middleware.mdx b/pages/aws/inner_workings/components/middleware.mdx index 96099c2c..296a8577 100644 --- a/pages/aws/inner_workings/components/middleware.mdx +++ b/pages/aws/inner_workings/components/middleware.mdx @@ -29,7 +29,7 @@ Since your app could be split into different origins, you need to be able to ret By default, it uses the `pattern-env` resolver which uses an `OPEN_NEXT_ORIGIN` environment variable to resolve the origin as well as the pattern defined in your `open-next.config.ts`. This env var should be a stringified version of an object of this shape: -```ts filename="open-next.config.ts" +```ts { // Key should be the same as the one used in `open-next.config.ts` for the functions [origin: string]: { From c35611d8bd2eaf0b1e954182079f85f97a17192f Mon Sep 17 00:00:00 2001 From: Victor Berchet Date: Mon, 27 Apr 2026 17:37:24 +0200 Subject: [PATCH 4/6] Apply suggestion from @vicb --- pages/aws/inner_workings/components/middleware.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/aws/inner_workings/components/middleware.mdx b/pages/aws/inner_workings/components/middleware.mdx index 296a8577..1d9f6260 100644 --- a/pages/aws/inner_workings/components/middleware.mdx +++ b/pages/aws/inner_workings/components/middleware.mdx @@ -44,7 +44,7 @@ By default, it uses the `pattern-env` resolver which uses an `OPEN_NEXT_ORIGIN` You can of course override this behavior by providing your own `originResolver` function in your `open-next.config.ts` file. This is the type of the `originResolver` function: -```ts filename="open-next.config.ts" +```ts type OriginResolver = BaseOverride & { resolve: (path: string) => Promise; }; From bef66ddb612be46301dda7e64f4001855f982e4b Mon Sep 17 00:00:00 2001 From: Akihiro Nagai <77012577+314systems@users.noreply.github.com> Date: Tue, 28 Apr 2026 07:12:06 +0900 Subject: [PATCH 5/6] Update pages/aws/common_issues.mdx Co-authored-by: Victor Berchet --- pages/aws/common_issues.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/aws/common_issues.mdx b/pages/aws/common_issues.mdx index a8ae0e3d..172c0caa 100644 --- a/pages/aws/common_issues.mdx +++ b/pages/aws/common_issues.mdx @@ -39,7 +39,7 @@ For example, Sentry does not remove server side sourcemaps, only client ones, ev You could exclude sourcemaps similarly: -```js +```js filename="next.config.js" outputFileTracingExcludes: { "*": [ './**/*.js.map', From 812980e7428c4aae509c542b55ddb9ba080dbe36 Mon Sep 17 00:00:00 2001 From: Akihiro Nagai <77012577+314systems@users.noreply.github.com> Date: Tue, 28 Apr 2026 07:16:13 +0900 Subject: [PATCH 6/6] revert --- pages/aws/v2/advanced/debugging.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pages/aws/v2/advanced/debugging.mdx b/pages/aws/v2/advanced/debugging.mdx index 3f6c77c6..dff7e0b2 100644 --- a/pages/aws/v2/advanced/debugging.mdx +++ b/pages/aws/v2/advanced/debugging.mdx @@ -8,8 +8,8 @@ If the server function is **deployed to Lambda@Edge**, the logs will appear in t The logs from the warmer function provide insights into the results of the warming process. -```json -{ "event": "warmer result", "sent": 2, "success": 2, "uniqueServersWarmed": 2 } +```plain +{ event: 'warmer result', sent: 2, success: 2, uniqueServersWarmed: 2 } ``` - `sent` — The number of times the warmer invoked the server function using the Lambda SDK. This value should correspond to the `CONCURRENCY` set in the warmer function.