You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
OpenNext can be executed in debug mode by setting the environment variable `OPEN_NEXT_DEBUG=true`.
2
4
3
-
You might stumble upon this error inside cloudwatch logs: `Cannot find module 'next'`.
4
-
It is likely that you are in a monorepo and you have several lock files.
5
-
Just make sure that you have a single lock file in the root of your project.
5
+
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**
6
6
7
-
#### headers, redirect, rewrites in `next-config` and middleware are not working in next 13.4.12+
7
+
```bash
8
+
OPEN_NEXT_DEBUG=true npx open-next@latest build
9
+
```
10
+
11
+
#### Cannot find module next
8
12
9
-
If you use a version of nextjs >= 13.4.12, you'll need to use an open-next version >= 2.1
13
+
You might stumble upon this error inside cloudwatch logs: `Cannot find module 'next'`. It is likely that you are in a monorepo and you have several lock files. **Just make sure that you have a single lock file in the root of your project.**
10
14
11
-
#### My api route are returning empty response and i'm using sentry
15
+
#### Reducing bundle size
12
16
13
-
If you are using sentry, API routes returns empty body. You could try configuring sentry to ignore API routes. You can read more about it [here](https://docs.sentry.io/platforms/javascript/guides/nextjs/manual-setup/?opt-out-of-auto-instrumentation-on-specific-routes)
17
+
Next might incorrectly include some dependencies in the bundle. To remove them you can use this configuration inside `next.config.js`:
14
18
15
-
#### My ISR page has this cache-control header `s-maxage=2, stale-while-revalidate=2592000`
19
+
```javascript
20
+
experimental: {
21
+
outputFileTracingExcludes: {
22
+
"*": ["node_modules/the-unwanted-package"],
23
+
},
24
+
},
25
+
```
26
+
Also you should not add sharp as a dependencies unless absolutely necessary, the image optimization already has it's own version of sharp.
16
27
17
-
Given how ISR works, while waiting for the revalidation to happen, the page will be served using this cache control header. This prevent your server from being overloaded by a lot of requests while the revalidation is done. You can read more about it [here](/inner_workings/isr).
#### Unzipped size must be smaller than 262144000 bytes
30
+
If you use ISR and fetch in your app, you may encounter a bug that makes your revalidate values inconsistent.
31
+
The issue is that it revalidates using the lowest revalidate of all fetch calls in your page, regardless of their individual values. To fix this bug, you need to modify the fetch function in your root layout component with the following code snippet
20
32
21
-
AWS Lambda has an unzipped size limit of 250MB. If your app is over this limit, then it is most likely using a node_module library that is too large for serverless or there is a large dev dependency getting bundled.
22
-
For example, `pdfjs` has `canvas` optional dependency which takes up 180MB. For more details, [read me](/common_issues/bundle_size).
23
-
Note: a large bundle size will increase cold start significantly.
1. Multiple deployment target means that you can deploy the same app to different target like some part to ECS, some part to Lambda etc...
18
+
2. Vercel supports only serverless Node (backed by AWS Lambda) and Edge runtime (backed by cloudflare workers)
19
+
2. You can deploy a dockerized next.js app to AWS lambda using AWS Lambda Web adapter, but some part like ISR will not work as expected
20
+
3. OpenNext supports external middleware, but it is not enabled by default.
21
+
4. OpenNext supports edge runtime in node, but every route needs to be deployed separately. OpenNext supports edge runtime in cloudflare workers, but only for app router api routes.
22
+
5. Embedded means that the edge runtime is embedded inside the bundle. It emulates a fake edge runtime inside the prod environment.
23
+
6. You might experience some inconsistencies with ISR if you have a CDN in front of your app. Next always set the cache-control header to `s-maxage=REVALIDATION_TIME, stale-while-revalidate`, it means that your data (json or rsc) and your html might be out of sync.
24
+
7. You need to invalidate the CDN manually. For OpenNext, here is an example for cloudfront
25
+
8. OpenNext supports custom server, but it is not enabled by default. You can have a custom server even in a serverless environment.
Copy file name to clipboardExpand all lines: docs/pages/config.mdx
+48-3Lines changed: 48 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,9 +1,18 @@
1
-
Here is a simple example of an `open-next.config.ts` file:
1
+
### Build Arguments
2
+
3
+
There is a single build argument that you can pass to the `open-next build` command:
4
+
-`--config-path` - This is the path to the configuration file that you want to use. By default, it will look for `open-next.config.ts` in the current working directory. This needs to be relative to the current working directory.
5
+
6
+
### Configuration File
7
+
8
+
For personalisation you need to create a file `open-next.config.ts` at the same place as your `next.config.js`, and export a default object that satisfies the `OpenNextConfig` interface.
9
+
10
+
Here is a detailed example of an `open-next.config.ts` file:
2
11
This file need to be at the same place as your `next.config.js` file
3
12
4
13
`server` in here could refer to a lambda function, a docker container, a node server or whatever that can support running nodejs code. (Even cloudflare workers in the future)
5
14
6
-
For more information about the options here, just look at the source file
15
+
For more information about the options here, take a look at the [components section](/components/overview).
// This is necessary to generate the dockerfile and for the implementation to know that it needs to deploy on docker
59
+
// You can also provide a string here which will be used to create the dockerfile
45
60
generateDockerfile: true,
46
61
},
47
62
},
@@ -58,10 +73,40 @@ const config = {
58
73
// It could be in lambda@edge, cloudflare workers, or anywhere else
59
74
// By default it uses lambda@edge
60
75
// This is not implemented in the reference construct implementation.
76
+
// This is optional, but might be necessary if you split your app into multiple servers
61
77
middleware: {
62
78
external: true
63
79
}
80
+
81
+
// Optional
82
+
imageOptimization: {
83
+
// This is the architecture of the image, it could be x64 or arm64
84
+
// This is necessary to bundle the proper version of sharp
85
+
arch: "x64",
86
+
}
87
+
88
+
// If you want to override the default build command, you can do it here
89
+
// By default it uses `npm run build`
64
90
buildCommand: "echo 'hello world'",
91
+
92
+
dangerous: {
93
+
// This will disable the tag cache
94
+
// You can use it safely on page router, on app router it will break revalidateTag and revalidatePath
95
+
disableTagCache: true,
96
+
// This will disable the incremental cache
97
+
// This is generally not recommended, as this is necessary for ISR AND SSG routes as well as the fetch cache
98
+
disableIncrementalCache: true,
99
+
}
100
+
101
+
//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 default to "."
102
+
buildOutputPath: "build",
103
+
104
+
//The path to the root of the Next.js app's source code. This path is relative from the current process.cwd(). - Optional default to "."
105
+
appPath: "app",
106
+
107
+
//The path to the package.json file of the Next.js app. This path is relative from the current process.cwd(). - Optional
OpenNext use 3 different esbuild plugins internally to recompile or modify the source code depending on some condition like the next version or the runtime used
2
+
3
+
#### OpenNext Replacement Plugin
4
+
5
+
This plugin is used to replace some code in the source code with some other code.
6
+
7
+
Here is a very simple example of how to use it:
8
+
9
+
```typescript
10
+
openNextPlugin({
11
+
// The target file to replace code in
12
+
target:/plugins\/default\.js/g,
13
+
// This is where the plugin will look for the code to replace
// This is to delete some code from the target file
16
+
deletes: ["id1"],
17
+
})
18
+
19
+
//To inject arbritary code by using (import at top of file):
20
+
21
+
//#import
22
+
23
+
importdatafrom'data'
24
+
const datum =data.datum
25
+
26
+
//#endImport
27
+
28
+
Toreplacecode:
29
+
30
+
//#override id1
31
+
32
+
exportfunction overrideMe() {
33
+
// I will replace the "id1" block in the target file
34
+
}
35
+
36
+
//#endOverride
37
+
```
38
+
39
+
#### OpenNext Resolve Plugin
40
+
41
+
This plugin is used to avoid having to bundle the whole library in the final bundle. It will replace the dynamic import of the overrides with the one that we want to use.
42
+
43
+
Here is a very simple example of how to use it:
44
+
45
+
```typescript
46
+
openNextResolvePlugin({
47
+
overrides: {
48
+
wrapper: "node",
49
+
converter: "node",
50
+
}
51
+
})
52
+
```
53
+
54
+
#### OpenNext Edge Plugin
55
+
56
+
This plugin is used to properly compile routes or middleware built for the `edge` runtime.
57
+
58
+
Here is a very simple example of how to use it:
59
+
60
+
```typescript
61
+
openNextEdgePlugin({
62
+
// The path to the .next directory
63
+
nextDir: "next",
64
+
// The path to the edgeFunctionHandler.js file that we'll use to bundle the routing
Copy file name to clipboardExpand all lines: docs/pages/index.mdx
+19-8Lines changed: 19 additions & 8 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,17 +1,31 @@
1
1
import {SITE} from"../config"
2
+
import { Callout } from'nextra/components'
2
3
3
-
### Open source Next.js serverless adapter
4
+
<Callout>
5
+
This docs is for the V3 of OpenNext. If you are looking for the V2 docs, you can find them [here](/v2).
6
+
7
+
If you're migrating from V2 to V3, you can find the migration guide [here](/migration#from-opennext-v2).
8
+
</Callout>
9
+
10
+
### Open source Next.js adapter
4
11
5
12
---
6
13
7
-
OpenNext takes the Next.js build output and converts it into a package that can be deployed to any functions as a service platform. As of now only AWS Lambda is supported.
8
14
15
+
OpenNext takes the Next.js build output and converts it into packages that can be deployed across a variety of environments.
16
+
Natively OpenNext has support for AWS Lambda and classic Node Server. It also offer partial support for the `edge` runtime in Cloudflare Workers.
17
+
18
+
One notable feature of OpenNext is its ability to split the Next.js output, enabling selective deployment to different targets such as AWS Lambda, Cloudflare Workers, or Amazon ECS. This facilitates a tailored deployment strategy that aligns with the specific needs of your application.
19
+
20
+
Thanks to this, you could deploy part of your API to ECS, another part to Cloudflare Workers, your SSR routes to another ECS cluster, and your ISR/SSG routes to Lambda.
9
21
10
22
---
11
23
12
24
While Vercel is great, it's not a good option if all your infrastructure is on AWS. Hosting it in your AWS account makes it easy to integrate with your backend. And it's a lot cheaper than Vercel.
13
25
14
-
Next.js, unlike Remix or Astro, doesn't have a way to self-host using serverless. You can run it as a Node application. This however doesn't work the same way as it does on Vercel.
26
+
Vercel is also limited to serverless and to their way of doing things. OpenNext is open source and can be deployed to any platform that supports Node.js.
27
+
28
+
Next.js, unlike Remix or Astro, doesn't have a way to self-host using **serverless**. You can run it as a Node application. This however doesn't work the same way as it does on Vercel.
15
29
16
30
---
17
31
@@ -23,10 +37,6 @@ Closed source SaaS products like [Amplify](https://aws.amazon.com/amplify/) have
23
37
24
38
---
25
39
26
-
The goal of OpenNext is to create an open source, framework agnostic, serverless adapter for Next.js.
27
-
28
-
OpenNext is currently built for AWS but we plan to support any functions as a service platform.
29
-
30
40
We need your help keeping it up to date and feature complete. Make sure to [**join us on Discord**](https://sst.dev/discord) and [**star us on GitHub**](https://github.com/sst/open-next).
31
41
## Features
32
42
@@ -48,4 +58,5 @@ OpenNext aims to support all Next.js 13 features. Some features are work in prog
0 commit comments