OpenNext V3

.changeset/rotten-trees-kiss.md

@@ -0,0 +1,38 @@
+---
+"open-next": major
+---
+
+OpenNext V3
+
+This is the V3 of OpenNext. It includes some breaking changes and cannot be used as a drop-in replacement for V2. If your IAC is using OpenNext V2, you will need to update it to use V3.
+
+If you are using OpenNext V2, please refer to the [migration guide](https://open-next.js.org/migration#from-opennext-v2) to upgrade to V3. 
+
+### New Features
+
+- Add support for function splitting
+- Add support for external middleware
+- Custom config file support : `open-next.config.ts`
+- Support for other deployment targets than lambda (Node.js, Docker and partial support for Cloudflare Workers)
+- Allow for customizing the outputs bundle :
+  - Wrapper
+  - Converter
+  - Incremental Cache (Fetch cache and HTML/JSON/RSC cache)
+  - Tag Cache
+  - Queue (Used to trigger ISR revalidation)
+  - Origin Resolver (Only for external middleware)
+  - Image Loader (Only for image optimization)
+  - Invoke function (For the warmer function)
+- Create an `open-next.output.json` file for easier integration with IAC tools
+
+### Breaking Changes
+
+- Edge runtime don't work out of the box anymore. You need to deploy them on a separate function see [the config for more info](https://open-next.js.org/config)
+- Output directory structure has changed to support function splitting
+- Removed build arguments in favor of `open-next.config.ts`
+
+### Internal Changes
+
+- Use OpenNextNodeResponse instead of ServerResponse (It uses transform stream to properly handle the stream)
+- Big refactor of the codebase to support function splitting
+- Added new plugins to support the new features and make the codebase more modular

docs/pages/inner_workings/_meta.json

@@ -2,4 +2,4 @@
   "caching": "Caching (ISR/SSG)",
   "components": "Main Components",
   "architecture": "Default Architecture"
-}
+}

docs/pages/v3/_meta.json

@@ -0,0 +1,7 @@
+{
+  "index": "What's new",
+  "config": "Configuration file",
+  "reference-implementation": "Reference Construct",
+  "requirements": "Requirements",
+  "override": "Advanced - Create your own override"
+}

docs/pages/v3/config.mdx

@@ -0,0 +1,69 @@
+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 { OpenNextConfig } 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
+        }
+      })
+    },
+  },
+  // Below we define the functions that we want to deploy in a different server
+  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: ['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",
+        // This is necessary to generate the dockerfile and for the implementation to know that it needs to deploy on docker
+        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.
+  middleware: {
+    external: true 
+  }
+  buildCommand: "echo 'hello world'",
+} satisfies OpenNextConfig
+
+export default config;
+export type Config = typeof config
+```

docs/pages/v3/index.mdx

@@ -0,0 +1,67 @@
+import { Callout } from 'nextra/components'
+
+<Callout type="warning" emoji="⚠️">
+
+`open-next@3.0.0-rc.3` 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)
+
+  This is a release candidate, it is mostly ready for production (You might still experience some quirks). We are looking for feedback on this release, so please try it out and let us know what you think. See [getting started](#get-started) to quickly test it.
+
+  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.
+
+  You could also use SST Ion which should support it out of the box pretty soon. See [here for more info](https://github.com/sst/ion) or in the [ion discord](https://discord.com/channels/983865673656705025/1177071497974648952).
+</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
+- Allow to move the middleware/routing part in a separate lambda or cloudflare workers in front of your server functions
+- An experimental bundled `NextServer` could be used which can reduce the size of your lambda by up to 24 MB
+- Experimental support for the `edge` runtime of next with some limitations:
+  - Only app router for now
+  - Only 1 route per function 
+  - Works fine in node, only for api route in cloudflare workers
+  - No support for `revalidateTag` or `revalidatePath` for now
+
+## Get started
+
+The easiest way to get started is to use the [reference implementation construct](/v3/reference-implementation). Copy this reference implementation into your project and then use it like that in your sst or cdk project:
+
+```ts
+import { OpenNextCdkReferenceImplementation } from "path/to/reference-implementation"
+
+const site = new OpenNextCdkReferenceImplementation(stack, "site", {
+  openNextPath: ".open-next",
+})
+```
+
+You also need to create an `open-next.config.ts` file in your project root, you can find more info [here](/v3/config).
+
+A very simple example of this file could be:
+
+```ts
+import type { OpenNextConfig } from 'open-next/types/open-next'
+const config = {
+  default: {
+
+  }
+}
+export default config;
+```
+
+Then you need to run `npx open-next@3.0.0-rc.3 build` to build your project before running the `sst deploy` or `cdk deploy` command to deploy your project.
+
+In V3 `open-next build` don't accept any arguments, all the args are passed in the `open-next.config.ts` file.

docs/pages/v3/override.mdx

@@ -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 { OpenNextConfig } from "open-next/types/open-next";
+
+function withGcp(config: TrimmedDownConfig): OpenNextConfig {
+  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: {
+    // ...
+  },
+});
+
+export default config;
+```