update docs for V3 (#351)

conico974 · web-flow · commit afd9605048cf · 2024-01-27T15:19:11.000+01:00
diff --git a/docs/pages/v3/_meta.json b/docs/pages/v3/_meta.json
@@ -2,5 +2,6 @@
   "index": "What's new",
   "config": "Configuration file",
   "reference-implementation": "Reference Construct",
+  "requirements": "Requirements",
   "override": "Advanced - Create your own override"
 }
diff --git a/docs/pages/v3/config.mdx b/docs/pages/v3/config.mdx
@@ -6,7 +6,7 @@ This file need to be at the same place as your `next.config.js` file
 For more information about the options here, just look at the source file
 
 ```ts
-import type { BuildOptions } from 'open-next/types/open-next'
+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 
@@ -62,8 +62,8 @@ const config = {
     external: true 
   }
   buildCommand: "echo 'hello world'",
-} satisfies BuildOptions
+} satisfies OpenNextConfig
 
-module.exports = config
-export type OpenNextConfig = typeof config
+export default config;
+export type Config = typeof config
 ```
diff --git a/docs/pages/v3/index.mdx b/docs/pages/v3/index.mdx
@@ -2,11 +2,13 @@ import { Callout } from 'nextra/components'
 
 <Callout type="warning" emoji="⚠️">
 
-`open-next@3.0.0-rc.2` 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)
+`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 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. See [getting started](#get-started) to quickly test it.
+  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?
@@ -26,8 +28,13 @@ import { Callout } from 'nextra/components'
   - 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
-- Support for the `edge` runtime of next (Only app router for now, only 1 route per function)
+- 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
 
@@ -46,13 +53,15 @@ You also need to create an `open-next.config.ts` file in your project root, you
 A very simple example of this file could be:
 
 ```ts
-import type { BuildOptions } from 'open-next/types/open-next'
+import type { OpenNextConfig } from 'open-next/types/open-next'
 const config = {
   default: {
 
   }
 }
-module.exports = config
+export default config;
 ```
 
-Then you need to run `npx open-next@3.0.0-rc.2 build` to build your project before running the `sst deploy` or `cdk deploy` command to deploy your project.
+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.
diff --git a/docs/pages/v3/override.mdx b/docs/pages/v3/override.mdx
@@ -18,9 +18,9 @@ A boilerplate for such a plugin could look like this (This is not real code):
 
 ```ts
 
-import { BuildOptions } from "open-next/types/open-next";
+import { OpenNextConfig } from "open-next/types/open-next";
 
-function withGcp(config: TrimmedDownConfig): BuildOptions {
+function withGcp(config: TrimmedDownConfig): OpenNextConfig {
   return {
     default: {
         override: {
@@ -70,5 +70,5 @@ const config = withGcp({
   },
 });
 
-module.exports = config;
+export default config;
 ```
diff --git a/docs/pages/v3/reference-implementation.mdx b/docs/pages/v3/reference-implementation.mdx
@@ -38,6 +38,10 @@ import {
 	Distribution,
 	ICachePolicy,
 	ViewerProtocolPolicy,
+	FunctionEventType,
+	OriginRequestPolicy,
+	Function as CloudfrontFunction,
+	FunctionCode,
 } from "aws-cdk-lib/aws-cloudfront";
 import { HttpOrigin, S3Origin } from "aws-cdk-lib/aws-cloudfront-origins";
 import {
@@ -347,13 +351,31 @@ export class OpenNextCdkReferenceImplementation extends Construct {
 	}
 
 	private createDistribution(origins: Record<string, HttpOrigin | S3Origin>) {
+		const cloudfrontFunction = new CloudfrontFunction(this, 'OpenNextCfFunction', {
+			code: FunctionCode.fromInline(`
+			function handler(event) {
+				var request = event.request;
+				request.headers["x-forwarded-host"] = request.headers.host;
+				return request;
+			}
+			`)
+		})
+		const fnAssociations = [
+			{
+				function: cloudfrontFunction ,
+				eventType: FunctionEventType.VIEWER_REQUEST,
+			},
+		]
+
 		const distribution = new Distribution(this, "OpenNextDistribution", {
 			defaultBehavior: {
 				origin: origins.default,
 				viewerProtocolPolicy: ViewerProtocolPolicy.REDIRECT_TO_HTTPS,
 				allowedMethods: AllowedMethods.ALLOW_GET_HEAD_OPTIONS,
 				cachedMethods: CachedMethods.CACHE_GET_HEAD_OPTIONS,
 				cachePolicy: this.serverCachePolicy,
+				originRequestPolicy: OriginRequestPolicy.ALL_VIEWER_EXCEPT_HOST_HEADER,
+				functionAssociations: fnAssociations
 			},
 			additionalBehaviors: this.openNextOutput.behaviors
 				.filter((b) => b.pattern !== "*")
@@ -372,6 +394,11 @@ export class OpenNextCdkReferenceImplementation extends Construct {
 									behavior.origin === "s3"
 										? this.staticCachePolicy
 										: this.serverCachePolicy,
+								originRequestPolicy: 
+									behavior.origin === "s3" 
+										? undefined 
+										: OriginRequestPolicy.ALL_VIEWER_EXCEPT_HOST_HEADER,
+								functionAssociations: fnAssociations
 							},
 						};
 					},
diff --git a/docs/pages/v3/requirements.mdx b/docs/pages/v3/requirements.mdx
@@ -0,0 +1,59 @@
+There is a couple of requirements necessary for open-next V3 to work.
+It will be divided by functionality. This is still WIP, feel free to open a PR if you think something is missing.
+
+## General
+- For the node runtime, you need at least Node 18.
+- For the edge runtime, you can use both Node 18+ or cloudflare workers with `node_compat` flag enabled (Cloudflare workers support is experimental)
+- Open-next doesn't work well on Windows. We recommend using WSL2 or a Linux VM.
+
+## ISR/SSG
+ISR/SSG has 2 types of cache, the Incremental Cache and the Tag Cache. To actually trigger the ISR revalidation, we use a Queue system. 
+
+The tag cache is only used in app router.
+### Incremental Cache
+By default we use S3 as the incremental cache. You can override this in `open-next.config.ts`. For this to work you need to provide server functions with the following environment variables:
+- CACHE_BUCKET_REGION
+- CACHE_BUCKET_NAME
+- CACHE_BUCKET_KEY_PREFIX
+
+### Tag Cache
+By default we use DynamoDb as the tag cache. For this to work you need to provide server functions with the following environment variables:
+- CACHE_DYNAMO_TABLE
+- CACHE_BUCKET_REGION
+
+### Queue
+By default we use SQS as the queue. fFr this to work you need to provide server functions with the following environment variables:
+- REVALIDATION_QUEUE_REGION
+- REVALIDATION_QUEUE_URL
+
+## External Middleware
+If you decide to use external middleware, you need to provide the following environment variables:
+- OPEN_NEXT_ORIGIN
+
+This env variable should contain a stringified version of this, with every key corresponding to the key used in functions inside `open-next.config.ts`: 
+```ts
+// For cloudflare workers
+// THIS IS TEMPORARY, WE WILL CHANGE THIS TO USE THE SAME FORMAT AS NODE
+{
+  default: "example.com",
+  ssr: "example2.com",
+  ssg: "example3.com"
+}
+// Or for node
+{
+  default: {
+    host: "example.com",
+    protocol: "https",
+    port: 443 // Optional
+    customHeaders: {
+      "x-custom-header": "value"
+    } // Optional, headers that you'd want to pass to the origin
+  },
+  ...
+}
+```
+
+## Image Optimization
+For image optimization to work, you need to provide the following environment variables:
+- BUCKET_NAME
+- BUCKET_KEY_PREFIX

Original file line number	Diff line number	Diff line change
`@@ -2,5 +2,6 @@`
`2`	`2`	`"index": "What's new",`
`3`	`3`	`"config": "Configuration file",`
`4`	`4`	`"reference-implementation": "Reference Construct",`
	`5`	`+ "requirements": "Requirements",`
`5`	`6`	`"override": "Advanced - Create your own override"`
`6`	`7`	`}`