Skip to content

Commit

Permalink
Initial docs for V3 (#330)
Browse files Browse the repository at this point in the history
* docs for V3

* fix link

* clearer routes in config
  • Loading branch information
conico974 authored Dec 7, 2023
1 parent ba6e176 commit 36da819
Show file tree
Hide file tree
Showing 4 changed files with 169 additions and 0 deletions.
5 changes: 5 additions & 0 deletions docs/pages/v3/_meta.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
{
"index": "What's new",
"config": "Configuration file",
"override": "Create your own override"
}
60 changes: 60 additions & 0 deletions docs/pages/v3/config.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,60 @@
Here is a simple example of an `open-next.config.ts` file:
This file need to be at the same place as your `next.config.js` file

`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)

For more information about the options here, just look at the source file

```ts
import type { BuildOptions } from 'open-next/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: {
wrapper: "aws-lambda-streaming", // This is necessary to enable lambda streaming
// You can override any part that is a `LazyLoadedOverride` this way
queue: () => Promise.resolve({
send: async (message) => {
//Your custom code here
}
})
},
},
functions: { // here we define the functions that we want to deploy in a different server
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: ['api/*', 'route1', 'route2', 'route3'], // patterns needs to be in a cloudfront compatible format, this will be used to generate the output
override: {
wrapper: "aws-lambda-streaming",
},
experimentalBundledNextServer: true // This enables the bundled next server which is faster and reduce the size of the server
},
pageSsr: {
routes: ["pages/pageSsr"], // For page dir routes should be in the form `pages/${route}` without the extension, it should match the filesystem
patterns: [ 'pageSsr', "_next/data/BUILD_ID/pageSsr.json"],
override: {
wrapper: "node",
converter: "node",
generateDockerfile: true,
},
},
},
// 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
middleware: {
external: true
}
buildCommand: "echo 'hello world'",
} satisfies BuildOptions

module.exports = config
export type OpenNextConfig = typeof config
```
30 changes: 30 additions & 0 deletions docs/pages/v3/index.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
import { Callout } from 'nextra/components'

<Callout type="warning" emoji="⚠️">

This is a release candidate, it is not yet ready for production, but we are getting close. We are looking for feedback on this release, so please try it out and let us know what you think.

`[email protected]` is here!!! Please report any issues you find on [discord](https://discord.com/channels/983865673656705025/1164872233223729152) or on the github [PR](https://github.com/sst/open-next/pull/327)

It also requires an updated version of the IAC tools that you use, see the sst PR [here](https://github.com/sst/sst/pull/3567) for more information
</Callout>

## What's new in V3?

- Rewritten server (We moved from the serverless-http `ServerResponse` into our own version which respect nodejs stream)
- A new `open-next.config.ts` file to configure your project
- Native support for aws lambda, aws lambda streaming, lambda@edge, node and docker
- In this `open-next.config.ts` you can now override a lot of things which allow for more customization:
- Wrapper component
- Converter component
- Incremental Cache
- Tag Cache
- Queue
- Custom warmer function
- Custom revalidation function
- Custom loader for image optimization
- Custom initialization function

- Allow for splitting, you can now split your next app into multiple servers, which could each have their own configuration
- An experimental bundled `NextServer` could be used which can reduce the size of your lambda by up to 24 MB
- ~~Support for the `edge` runtime of next~~ (coming soon)
74 changes: 74 additions & 0 deletions docs/pages/v3/override.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,74 @@
In this version of open-next, you could override a lot of the default behaviour.

For some real example of how to override each behaviour:
- [Wrapper](https://github.com/conico974/open-next/blob/feat/splitting/packages/open-next/src/wrappers/aws-lambda.ts)
- [Converter](https://github.com/conico974/open-next/blob/feat/splitting/packages/open-next/src/converters/aws-apigw-v2.ts)
- [IncrementalCache](https://github.com/conico974/open-next/blob/feat/splitting/packages/open-next/src/cache/incremental/s3.ts)
- [TagCache](
https://github.com/conico974/open-next/blob/feat/splitting/packages/open-next/src/cache/tag/dynamoDb.ts
)
- [Queue](
https://github.com/conico974/open-next/blob/feat/splitting/packages/open-next/src/queue/sqs.ts
)

This means it could allow people to write their own custom open-next.
For example you could create a custom `withGcp` plugin to allow to deploy open-next on GCP functions

A boilerplate for such a plugin could look like this (This is not real code):

```ts

import { BuildOptions } from "open-next/types/open-next";

function withGcp(config: TrimmedDownConfig): BuildOptions {
return {
default: {
override: {
wrapper: async () => (await import("./gcp-wrapper")).default,
converter: async () => (await import("./gcp-converter")).default,
incrementalCache: async () => (await import("./gcp-incremental-cache")).default,
tagCache: async () => (await import("./gcp-tag-cache")).default,
queue: async () => (await import("./gcp-queue")).default,
},
...config.default,
},
functions: {
// Same as default but for each splitted function
//...
}
warmer: {
override: {
wrapper: async () => (await import("./gcp-wrapper")).default,
converter: async () => (await import("./gcp-converter")).default,
},
invokeFunction: async () => (await import("./gcp-invoke-function")).default,
},
revalidate: {
override: {
wrapper: async () => (await import("./gcp-wrapper")).default,
converter: async () => (await import("./gcp-queue-converter")).default,
},
},
imageOptimization: {
override: {
wrapper: async () => (await import("./gcp-wrapper")).default,
converter: async () => (await import("./gcp-converter")).default,
},
loader: async () => (await import("./gcp-object-loader")).default,
},
}
}
```

Using this plugin would look like this inside `open-next.config.ts`:

```ts
import { withGcp } from "./with-gcp";
const config = withGcp({
default: {
// ...
},
});

module.exports = config;
```

1 comment on commit 36da819

@vercel
Copy link

@vercel vercel bot commented on 36da819 Dec 7, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Successfully deployed to the following URLs:

open-next – ./

open-next-sst-dev.vercel.app
open-next-git-main-sst-dev.vercel.app
open-next.vercel.app

Please sign in to comment.