OpenNext

https://opennext.js.org/
Admin
OpenNext is an initiative to enable self-hosting of Next.js applications across various platforms...
Tokens:74,726
Snippets:549
Trust Score:8.1
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Install sharp on default server with ARM64 architecture

Source: https://opennext.js.org/aws/config/reference

Configures the default server to install sharp@0.33.5 with ARM64 architecture. The 'install' option is used to add packages and set architecture. This example shows the required structure for open-next.config.ts.

```typescript
import type { OpenNextConfig } from '@opennextjs/aws/types/open-next';
const config = {
default: {
  install: {
    packages: ['sharp@0.33.5'],
    arch: 'arm64',
  },
},
} satisfies OpenNextConfig;
 
export default config;
```

--------------------------------

### Run the migrate command

Source: https://opennext.js.org/cloudflare/cli

Run this command in an existing Next.js project to convert it to an OpenNext-compatible one. It automates setup steps including installing dependencies, creating configuration files, and setting up local development.

```bash
npx @opennextjs/cloudflare migrate
```

--------------------------------

### open-next.local.config.ts for local development

Source: https://opennext.js.org/aws/contribute/local_run

Example open-next.local.config.ts file for local development. Uses express-dev wrapper, node converter, fs-dev caches, and direct queue. Includes image optimization overrides with sharp installation for x64 Linux. The buildCommand is commented out as an optional override.

```typescript
// 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.
import type { OpenNextConfig } from "@opennextjs/aws/types/open-next.js";
 
export default {
  default: {
    override: {
      wrapper: "express-dev",
      converter: "node",
      incrementalCache: "fs-dev",
      queue: "direct",
      tagCache: "fs-dev",
    },
  },
 
  imageOptimization: {
    override: {
      wrapper: "dummy",
      converter: "dummy",
    },
    loader: "fs-dev",
    // This part is not needed on arm linux, and image optimization will only work in linux
    install: {
      arch: "x64",
      packages: ["sharp"],
    },
  },
 
  // You can override the build command here so that you don't have to rebuild next every time you make a change
  //buildCommand: "echo 'No build command'",
} satisfies OpenNextConfig;
 
export default config;
```

--------------------------------

### List commands and get help

Source: https://opennext.js.org/cloudflare/cli

Use `pnpm opennextjs-cloudflare` to list commands and `pnpm opennextjs-cloudflare <command> --help` to get help for a specific command.

```bash
pnpm opennextjs-cloudflare
```

```bash
pnpm opennextjs-cloudflare <command> --help
```

--------------------------------

### Install SST in Next.js App

Source: https://opennext.js.org/aws/config/nx

Initializes SST and resolves type errors in the project. Run from the app directory.

```bash
$ cd apps/next-site && sst install
```

--------------------------------

### Install @opennextjs/cloudflare

Source: https://opennext.js.org/cloudflare/get-started

Installs the @opennextjs/cloudflare package as a dependency.

```bash
npm install @opennextjs/cloudflare@latest
```

--------------------------------

### OpenNext Configuration Example

Source: https://opennext.js.org/aws/config/full_example

Full example of an OpenNext configuration file. It includes settings for revalidate, warmer, build command, dangerous options like disabling caches and cache interception, and path configurations. The configuration is typed with OpenNextConfig and exported as default.

```typescript
// By default, works for lambda and on SQS event.
  // Supports only node runtime
  revalidate: {
    override: {
      wrapper: "aws-lambda", // Can be overridden with a LazyLoadedOverride
      converter: "aws-apigw-v2", // Can be overridden with a LazyLoadedOverride
    },
  },
  // Override the default warmer
  // By default, works for lambda only.
  // If you override this, you'll need to handle the warmer event in the wrapper
  warmer: {
    invokeFunction: "aws-lambda", // Can be overridden with a LazyLoadedOverride
    override: {
      wrapper: "aws-lambda", // Can be overridden with a LazyLoadedOverride
      converter: "aws-apigw-v2", // Can be overridden with a LazyLoadedOverride
    },
  },
  // If you want to override the default build command, you can do it here
  // By default it uses `npm run build`
  buildCommand: "echo 'skipping build'",
 
  dangerous: {
    // This will disable the tag cache
    // You can use it safely on page router, on app router it will break revalidateTag and revalidatePath
    disableTagCache: true,
    // This will disable the incremental cache
    // This is generally not recommended, as this is necessary for ISR AND SSG routes as well as the fetch cache
    disableIncrementalCache: true,
    // Enable the cache interception. Every request will go through the cache interceptor, if it is found in the cache,
    // it will be returned without going through NextServer. Not every feature is covered by the cache interceptor and
    // it should fallback to the NextServer if the cache is not found.
    enableCacheInterception: true,
    // Function to determine which headers or cookies takes precedence.
    // By default, the middleware headers and cookies will override the handler headers and cookies.
    // This is executed for every request and after next config headers and middleware has executed.
    // Here is a very simple example of how you can use it:
    headersAndCookiesPriority: (event) => {
      if (event.rawPath.startsWith("/api")) {
        return "middleware";
      }
      return "handler";
    },
  },
  // The path to the target folder of build output from the `buildCommand` option
  // (the path which will contain the `.next` and `.open-next` folders).
  // This path is relative from the current process.cwd() - Optional defaults to "."
  buildOutputPath: "build",
  // The path to the root of the Next.js app's source code.
  // This path is relative from the current process.cwd(). - Optional defaults to "."
  appPath: "app",
  // The path to the package.json file of the Next.js app.
  // This path is relative from the current process.cwd(). - Optional
  packageJsonPath: "package.json",
  // Advanced usage
  // If you use the edge runtime somewhere (either with an external middleware or in the functions), we compile 2 versions of the open-next.config.ts file.
  // One for the node runtime and one for the edge runtime.
  // This option allows you to specify the externals for the edge runtime used in esbuild for the compilation of open-next.config.ts
  // It is especially useful if you use some custom overrides only in node
  edgeExternals: [],
} satisfies OpenNextConfig;
 
export default config;
```

--------------------------------

### OpenNext Replacement Plugin example

Source: https://opennext.js.org/aws/contribute/plugin

Configures the replacement plugin to replace code in a target file, with replacements, deletes, and markers for injecting or overriding code.

```javascript
openNextPlugin({
    // The target file to replace code in
    target: /plugins\/default\.js/g,
    // This is where the plugin will look for the code to replace
    replacements: [require.resolve("./plugins/default.js")],
    // This is to delete some code from the target file
    deletes: ["id1"],
  })
```

--------------------------------

### OpenNext Edge Plugin example

Source: https://opennext.js.org/aws/contribute/plugin

Configures the edge plugin with the .next directory, edge function handler path, middleware info, and a flag for Cloudflare Workers.

```javascript
openNextEdgePlugin({
  // The path to the .next directory
  nextDir: "next",
  // The path to the edgeFunctionHandler.js file that we'll use to bundle the routing
  edgeFunctionHandlerPath: "./edgeFunctionHandler.js",
  // The middlewareInfo from the middleware manifest file
  middlewareInfo: middlewareInfo
  // If the app should be bundled for cloudflare workers
  isInCloudflare: true
})
```

--------------------------------

### OpenNext Resolve Plugin example

Source: https://opennext.js.org/aws/contribute/plugin

Configures the resolve plugin to specify overrides for the wrapper and converter, avoiding bundling the whole library.

```javascript
openNextResolvePlugin({
  overrides: {
    wrapper: "node",
    converter: "node",
  },
});
```

--------------------------------

### open-next.config.ts full configuration example

Source: https://opennext.js.org/aws/config/full_example

This configuration file must be placed alongside next.config.js. It customizes the default server with overrides for streaming, converter, cache, and queue, and defines additional functions for SSR, page SSR, and edge runtime. It also configures middleware, image optimization, and initialization function.

```typescript
import type { OpenNextConfig } from "@opennextjs/aws/types/open-next";
const config = {
  default: {
    // This is the default server, similar to the server-function in open-next v2
    // You don't have to provide the below, by default it will generate an output
    // for normal lambda as in open-next v2
    override: {
      // This is necessary to enable lambda streaming, defaults to aws-lambda
      wrapper: "aws-lambda-streaming",
      // Convert the input and output of the server, defaults to aws-apigw-v2
      converter: "aws-apigw-v2",
      // Used for fetch cache and html/rsc/json cache, defaults to s3
      incrementalCache: "s3",
      // Used for external rewrites, defaults to node
      proxyExternalRequest: "node",
      tagCache: "dynamodb", // Used for revalidatePath and revalidateTag, defaults to dynamodb
      // You can override any part that is a `LazyLoadedOverride` this way
      queue: () =>
        Promise.resolve({
          send: async (message) => {
            //Your custom code here
          },
        }),
    },
    // this will install sharp to your default server function
    // only for example purposes, you most likely should not use this
    // this can be used on every server to install additional packages
    install: {
      packages: ["sharp@0.33.5"],
      arch: "arm64",
    },
    minify: true, // This will minify the output
  },
  // Below we define the functions that we want to deploy in a different server
  // This is only used if you want to split the server into multiple servers
  functions: {
    ssr: {
      routes: [
        "app/api/isr/route",
        "app/api/sse/route",
        "app/api/revalidateTag/route", // app dir Api routes
        "app/route1/page",
        "app/route2/page", // app dir pages
        "pages/route3", // page dir pages
      ], // For app dir, you need to include route|page, no need to include layout or loading
      // patterns needs to be in a cloudfront compatible format
      // this will be used to generate the output
      patterns: ["api/*", "route1", "route2", "route3"],
      override: {
        wrapper: "aws-lambda-streaming",
      },
      // This enables the bundled next server which is faster and reduce the size of the server
      // This is also experimental and might not work in all cases
      experimentalBundledNextServer: true, // deprecated and not supported in next 14.2+
    },
    pageSsr: {
      // For page dir routes should be in the form `pages/${route}` without the extension
      // It should match the filesystem
      routes: ["pages/pageSsr"],
      // BUILD_ID is a special case, it will be replaced with the actual build id
      patterns: ["pageSsr", "_next/data/BUILD_ID/pageSsr.json"],
      override: {
        wrapper: "node",
        converter: "node",
        // This is necessary to generate the dockerfile and
        // for the implementation to know that it needs to deploy on docker
        // You can also provide a string here which will be used to create the dockerfile
        generateDockerfile: true,
      },
    },
    edge: {
      runtime: "edge",
      routes: ["app/ssr/page"],
      patterns: ["ssr"],
      override: {},
    },
  },
  // By setting this, it will create another bundle for the middleware,
  // and the middleware will be deployed in a separate server.
  // If not set middleware will be bundled inside the servers
  // It could be in lambda@edge, cloudflare workers, or anywhere else
  // By default it uses lambda@edge
  // This is not implemented in the reference construct implementation.
  // This is optional, but might be necessary if you split your app into multiple servers
  middleware: {
    external: true,
  },
  // Optional
  imageOptimization: {
    loader: "s3-lite", // Can be overridden with a LazyLoadedOverride
    // This is necessary to bundle the proper version of sharp
    // You can customize this to your needs
    // By default it will install with these options:
    install: {
      packages: ["sharp@0.32.6"],
      arch: "arm64",
      nodeVersion: "18",
      libc: "glibc",
    },
  },
  // Initialization function is a special server that will run at build time to initialize the cache.
  // By default, it only initializes the tag cache. Besides the common options, you can use the following options:
  initializationFunction: {
    tagCache: "dynamodb-lite", // Can be overridden with a LazyLoadedOverride
  },
  // Override the default revalidate function
}
```

--------------------------------

### Command-specific options and wrangler options

Source: https://opennext.js.org/cloudflare/cli

Commands accept command-specific options and wrangler options. Example: `pnpm opennextjs-cloudflare build --skipNextBuild --noMinify` and `pnpm opennextjs-cloudflare build --config=/path/to/wrangler.jsonc --env=prod`.

```bash
pnpm opennextjs-cloudflare build --skipNextBuild --noMinify
```

```bash
pnpm opennextjs-cloudflare build --config=/path/to/wrangler.jsonc --env=prod
```

--------------------------------

### Enable aws4fetch in open-next.config.ts

Source: https://opennext.js.org/aws/config/simple_example

Use aws4fetch instead of AWS SDK v3 to reduce cold starts by up to 300ms. Requires OpenNext v3.0.3+ and overrides tagCache, incrementalCache, and queue to their 'lite' variants.

```typescript
import type { OpenNextConfig } from "@opennextjs/aws/types/open-next.js";
const config = {
  default: {
    override: {
      tagCache: "dynamodb-lite",
      incrementalCache: "s3-lite",
      queue: "sqs-lite",
    },
  },
} satisfies OpenNextConfig;
 
export default config;
```

--------------------------------

### Configure edge runtime function in open-next.config.ts

Source: https://opennext.js.org/aws/config/simple_example

Configure an edge runtime function in open-next.config.ts. This generates two server functions: the default and the edge one. The edge function is deployed as a lambda in the edge runtime, which reduces cold start time but only allows one route per function and does not bundle middleware. Uncomment the placement option to deploy globally as lambda@edge; otherwise it deploys in the region specified in the stack.

```typescript
import type { OpenNextConfig } from "@opennextjs/aws/types/open-next.js";
const config = {
  default: {},
  functions: {
    edge: {
      runtime: "edge",
      //placement: "global", If you want your function to be deployed globally (i.e. lambda@edge) uncomment this line. Otherwise it will be deployed in the region specified in the stack
      routes: ["app/api/test/route"],
      patterns: ["api/test"],
    },
  },
} satisfies OpenNextConfig;
 
export default config;
```

--------------------------------

### Access bindings in a Next.js route with getCloudflareContext

Source: https://opennext.js.org/cloudflare/bindings

Use getCloudflareContext to access bindings like KV from any route. This example shows a GET handler that writes and reads a value from a KV namespace.

```typescript
import { getCloudflareContext } from "@opennextjs/cloudflare";
 
export async function GET(request) {
  const myKv = getCloudflareContext().env.MY_KV_NAMESPACE;
  await myKv.put("foo", "bar");
  const foo = await myKv.get("foo");
 
  return new Response(foo);
}
```

--------------------------------

### Preview app locally

Source: https://opennext.js.org/cloudflare/perf

Launches a local version of the application to record a CPU profile. Follow the Workers documentation steps after running this command.

```bash
opennextjs-cloudflare preview
```

--------------------------------

### Gradual deployment: server at 100%

Source: https://opennext.js.org/cloudflare/howtos/multi-worker

Completes the rollout by deploying the new server version at 100% traffic.

```bash
wrangler versions deploy <NEW_SERVER_VERSION_ID>@100% -y --config ./path-to/server-wrangler.jsonc
```

--------------------------------

### Build and run OpenNext locally

Source: https://opennext.js.org/aws/contribute

Steps to build and run OpenNext locally: first build the open-next package, then run it in watch mode, and finally build a Next.js app using the local build to test changes.

```bash
cd opennextjs-aws
pnpm build

```

```bash
pnpm dev

```

```bash
cd path/to/my/nextjs/app
path/to/opennextjs-aws/packages/open-next/dist/index.js build

```

--------------------------------

### Install Wrangler CLI as devDependency

Source: https://opennext.js.org/cloudflare/get-started

Installs the Wrangler CLI as a devDependency. Wrangler version 3.99.0 or later is required to deploy Next.js apps using @opennextjs/cloudflare.

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

--------------------------------

### package.json exports example

Source: https://opennext.js.org/cloudflare/troubleshooting

Example of a package.json exports field with multiple conditions. Wrangler uses esbuild to choose which export to use, which may be incompatible with some NPM packages.

```json
"exports": {
    "other": "./src/other.js",
    "node": "./src/node.js",
    "browser": "./src/browser.js",
    "default": "./src/default.js"
},
```

--------------------------------

### Build and inspect bundle for size limit

Source: https://opennext.js.org/cloudflare/troubleshooting

Commands to build the project and navigate to the bundled code directory. The third step is to take the file named handler.mjs.meta.json and use the ESBuild Bundle Analyzer to visualize the application's code.

```bash
npx @opennextjs/cloudflare build
```

```bash
cd .open-next/server-functions/default
```

--------------------------------

### Sentry server-side setup with instrumentation.ts and sentry.server.config.ts

Source: https://opennext.js.org/aws/common_issues

Working Sentry server-side setup that avoids dynamic imports in instrumentation.ts, which cause the 'cannot find module ./chunks/xxxx.js' error. The instrumentation.ts file imports initSentry from sentry.server.config.ts, which initializes Sentry with the runtime.

```typescript
import * as Sentry from "@sentry/nextjs";
import { initSentry } from "../sentry.server.config";
 
export const onRequestError = Sentry.captureRequestError;
 
export async function register() {
  initSentry(process.env.NEXT_RUNTIME as "nodejs" | "edge");
}
```

```typescript
import * as Sentry from "@sentry/nextjs";
 
export const initSentry = (runtime: "nodejs" | "edge") => {
  Sentry.init({
    dsn: "https://...",
 
    //...rest of your config
  });
};
```

--------------------------------

### Gradual deployment: server at 0%

Source: https://opennext.js.org/cloudflare/howtos/multi-worker

Deploys the new server version at 0% traffic while keeping the current version at 100%. This is the first step in the gradual rollout.

```bash
wrangler versions deploy <CURRENT_SERVER_ID>@100% <NEW_SERVER_VERSION_ID>@0% -y --config ./path-to/server-wrangler.jsonc
```

--------------------------------

### Access Denied error XML example

Source: https://opennext.js.org/aws/common_issues

Example of an Access Denied error in XML that may occur when refreshing a dynamic/static route or accessing it directly via URL. This can also happen in app router when a client navigates via NextJS <Link> component. The issue might be an overlapping folder or file in the public directory.

```xml
<Error>
   <Code>AccessDenied</Code>
   <Message>Access Denied</Message>
   <RequestId>R4E6T9G2Q1S0Z5X8</RequestId>
   <HostId>S7h9F3g2T0z5K8d6A2s1W4x3C7v8B9m2L0j3K4i7H8g9F0r3A5q8w9E8r7t6Y5h4U3i2O1p0</HostId>
</Error>
```

--------------------------------

### Build and run OpenNext locally

Source: https://opennext.js.org/aws/contribute/local_run

Builds OpenNext locally with a custom config file, then runs the server. The config-path flag is required if you use a different config name than the default.

```bash
# 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
node .open-next/server-functions/default/index.mjs
```

--------------------------------

### Hyperdrive per-request Prisma client with PrismaPg

Source: https://opennext.js.org/cloudflare/howtos/db

Hyperdrive setup using the PrismaPg adapter with the connection string from env.HYPERDRIVE.connectionString. getDbAsync is for static routes (ISR/SSG).

```typescript
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
import { cache } from "react";
import { PrismaClient } from "@prisma/client";
import { PrismaPg } from "@prisma/adapter-pg";
 
export const getDb = cache(() => {
  const { env } = getCloudflareContext();
  const connectionString = env.HYPERDRIVE.connectionString;
  const adapter = new PrismaPg({ connectionString, maxUses: 1 });
  return new PrismaClient({ adapter });
});
 
// This is the one to use for static routes (i.e. ISR/SSG)
export const getDbAsync = async () => {
  const { env } = await getCloudflareContext({ async: true });
  const connectionString = env.HYPERDRIVE.connectionString;
  const adapter = new PrismaPg({ connectionString, maxUses: 1 });
  return new PrismaClient({ adapter });
};

```

--------------------------------

### Deploy middleware at 100%

Source: https://opennext.js.org/cloudflare/howtos/multi-worker

Deploys the new middleware version at 100% traffic. This step makes the new version of the website live in production.

```bash
wrangler versions deploy <NEW_MIDDLEWARE_ID>@100% -y --config ./path-to/middlewareWrangler.jsonc
```

--------------------------------

### Get current server deployment status

Source: https://opennext.js.org/cloudflare/howtos/multi-worker

Retrieves the currently deployed version ID of the server worker. The output includes the version ID needed for the gradual deployment step.

```bash
wrangler deployments status --config ./path-to/server-wrangler.jsonc
```

--------------------------------

### Create open-next.config.ts for Nx monorepo

Source: https://opennext.js.org/aws/config/nx

Create the OpenNext configuration file in the app root. The `buildCommand` is set to `exit 0` because Nx task distribution handles the build order. `packageJsonPath` points to the repository root where the root `package.json` resides.

```typescript
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)
} satisfies OpenNextConfig;
 
export default config;
```

--------------------------------

### package.json conditional exports for workerd

Source: https://opennext.js.org/cloudflare/howtos/workerd

Example of conditional exports in package.json that include a workerd-specific entrypoint. Node.js uses the import or default condition, while workerd uses the workerd condition.

```json
"exports": {
  "types": "./types/index.d.ts",
  "bun": "./src/index.js",
  "workerd": "./cf/src/index.js",
  "import": "./src/index.js",
  "default": "./cjs/src/index.js"
},
```

--------------------------------

### Deploy Next.js App with Nx

Source: https://opennext.js.org/aws/config/nx

Commands to deploy the Next.js app using Nx. Use --configuration dev to set the stage to development, -c dev as shorthand, or --stage to specify a custom stage.

```bash
$ 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
```

--------------------------------

### invalidateCloudFrontPaths function

Source: https://opennext.js.org/aws/inner_workings/caching

Example implementation of the `invalidateCloudFrontPaths()` function using the AWS SDK for JavaScript. It creates a CloudFront invalidation for the given paths. You must set the CloudFront distribution ID.

```typescript
import { CloudFrontClient, CreateInvalidationCommand } from "@aws-sdk/client-cloudfront";
 
const cloudFront = new CloudFrontClient({});
 
async function invalidateCloudFrontPaths(paths: string[]) {
  await cloudFront.send(
    new CreateInvalidationCommand({
      // Set CloudFront distribution ID here
      DistributionId: distributionId,
      InvalidationBatch: {
        CallerReference: `${Date.now()}`,
        Paths: {
          Quantity: paths.length,
          Items: paths,
        },
      },
    })
  );
}

```

--------------------------------

### Add open-next.config.ts file

Source: https://opennext.js.org/cloudflare/get-started

Configuration file for OpenNext. Uses the defineCloudflareConfig function and sets the incremental cache to use R2. To use the OpenNextConfig type (not necessary), install @opennextjs/aws as a dev dependency.

```typescript
import { defineCloudflareConfig } from "@opennextjs/cloudflare";
import r2IncrementalCache from "@opennextjs/cloudflare/overrides/incremental-cache/r2-incremental-cache";
 
export default defineCloudflareConfig({
  incrementalCache: r2IncrementalCache,
});
```
Tokens:
Raw