Docs for V3 (#400)

* moved old docs to V2

* removed V3 folder

* base V3 docs

* wip

* mostly final docs

Author: conico974

Diff for: docs/pages/_meta.json

@@ -1,8 +1,10 @@
 {
   "index": "Home",
   "get_started": "Getting started",
-  "common_issues": "Common issues",
+  "config": "Configuration",
+  "comparison": "Comparison",
   "inner_workings": "How does it work?",
-  "advanced": "Advanced",
-  "faq": "FAQ"
+  "faq": "FAQ",
+  "common_issues": "Troubleshooting",
+  "contribute": "Contributing"
 }

Diff for: docs/pages/common_issues.mdx

@@ -1,23 +1,42 @@
-#### Cannot find module next
+#### Debug mode 
+
+OpenNext can be executed in debug mode by setting the environment variable `OPEN_NEXT_DEBUG=true`. 
 
-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.
+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**
 
-#### headers, redirect, rewrites in `next-config` and middleware are not working in next 13.4.12+
+```bash
+OPEN_NEXT_DEBUG=true npx open-next@latest build
+```
+
+#### Cannot find module next
 
-If you use a version of nextjs >= 13.4.12, you'll need to use an open-next version >= 2.1
+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.**
 
-#### My api route are returning empty response and i'm using sentry
+#### Reducing bundle size
 
-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)
+Next might incorrectly include some dependencies in the bundle. To remove them you can use this configuration inside `next.config.js`:
 
-#### My ISR page has this cache-control header `s-maxage=2, stale-while-revalidate=2592000`
+```javascript
+experimental: {
+    outputFileTracingExcludes: {
+      "*": ["node_modules/the-unwanted-package"],
+    },
+  },
+```
+Also you should not add sharp as a dependencies unless absolutely necessary, the image optimization already has it's own version of sharp.
 
-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).
+#### Patch fetch behaviour for ISR. Only for [email protected]+
 
-#### Unzipped size must be smaller than 262144000 bytes
+If you use ISR and fetch in your app, you may encounter a bug that makes your revalidate values inconsistent. 
+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
 
-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.
-For example, `pdfjs` has `canvas` optional dependency which takes up 180MB. For more details, [read me](/common_issues/bundle_size).
-Note: a large bundle size will increase cold start significantly.
+```ts
+export default function RootLayout() {
+  const asyncStorage = require("next/dist/client/components/static-generation-async-storage.external");
+  //@ts-ignore
+  const staticStore = (fetch as any).__nextGetStaticStore?.() || asyncStorage.staticGenerationAsyncStorage;
+  const store = staticStore.getStore();
+  store.isOnDemandRevalidate = store.isOnDemandRevalidate && !(process.env.OPEN_NEXT_ISR === 'true');
+  return <>...</>;
+}
+```

Diff for: docs/pages/comparison.mdx

@@ -0,0 +1,25 @@
+It should be noted that open-next does not actually deploy the app. It only bundles everything for your IAC to deploy it. 
+
+Here is a table comparing the different options to deploy a next.js app:
+
+| Features | OpenNext | Vercel | AWS Amplify | Docker Standalone |
+| --- | --- | --- | --- | --- |
+| **Function splitting** | Yes | Yes | No | No |
+| **Multiple deployment target** ¹ | Yes | Yes ² | No | No |
+| **Serverless** | Yes | Yes | Yes | No ³ |
+| **Warmer function** | Yes | No | No | Not necessary |
+| **External middleware** | Yes ⁴ | Yes | No | No |
+| **Edge runtime support** | Partial Support ⁵ | Yes | Embedded ⁶ | Embedded ⁶ |
+| **ISR** | Yes | Yes | Yes | Yes ⁷ |
+| **On-Demand Revalidation** | Yes ⁸ | Yes | No | Yes ⁸ |
+| **Custom server** | Yes ⁹ | No | No | Yes |
+
+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...
+2. Vercel supports only serverless Node (backed by AWS Lambda) and Edge runtime (backed by cloudflare workers)
+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
+3. OpenNext supports external middleware, but it is not enabled by default.
+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.
+5. Embedded means that the edge runtime is embedded inside the bundle. It emulates a fake edge runtime inside the prod environment.
+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.
+7. You need to invalidate the CDN manually. For OpenNext, here is an example for cloudfront
+8. OpenNext supports custom server, but it is not enabled by default. You can have a custom server even in a serverless environment.

Diff for: docs/pages/v3/config.mdx renamed to docs/pages/config.mdx

@@ -1,9 +1,18 @@
-Here is a simple example of an `open-next.config.ts` file: 
+### Build Arguments
+
+There is a single build argument that you can pass to the `open-next build` command: 
+- `--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.
+
+### Configuration File
+
+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.
+
+Here is a detailed 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
+For more information about the options here, take a look at the [components section](/components/overview).
 
 ```ts
 import type { OpenNextConfig } from 'open-next/types/open-next'
@@ -20,8 +29,10 @@ const config = {
         }
       })
     },
+    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: [
@@ -33,15 +44,19 @@ const config = {
       override: {
         wrapper: "aws-lambda-streaming",
       },
-      experimentalBundledNextServer: true // This enables the bundled next server which is faster and reduce the size of the server
+      // 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 
     },
     pageSsr: {
       routes: ["pages/pageSsr"], // For page dir routes should be in the form `pages/${route}` without the extension, it should match the filesystem
+      // 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,
       },
     },
@@ -58,10 +73,40 @@ const config = {
   // 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: {
+    // This is the architecture of the image, it could be x64 or arm64
+    // This is necessary to bundle the proper version of sharp
+    arch: "x64", 
+  }
+
+  // If you want to override the default build command, you can do it here
+  // By default it uses `npm run build`
   buildCommand: "echo 'hello world'",
+
+  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, 
+  }
+
+  //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 "."
+  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 default 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",
+
 } satisfies OpenNextConfig
 
 export default config;

Diff for: docs/pages/advanced/contribute.mdx renamed to docs/pages/contribute.mdx

@@ -0,0 +1,71 @@
+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
+
+#### OpenNext Replacement Plugin
+
+This plugin is used to replace some code in the source code with some other code. 
+
+Here is a very simple example of how to use it:
+
+```typescript
+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"],
+  })
+ 
+  //To inject arbritary code by using (import at top of file):
+ 
+  //#import
+ 
+  import data from 'data'
+  const datum = data.datum
+ 
+  //#endImport
+ 
+  To replace code:
+ 
+  //#override id1
+ 
+  export function overrideMe() {
+     // I will replace the "id1" block in the target file
+  }
+ 
+  //#endOverride
+```
+
+#### OpenNext Resolve Plugin
+
+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.
+
+Here is a very simple example of how to use it:
+
+```typescript
+openNextResolvePlugin({
+  overrides: {
+    wrapper: "node",
+    converter: "node",
+  }
+})
+```
+
+#### OpenNext Edge Plugin
+
+This plugin is used to properly compile routes or middleware built for the `edge` runtime. 
+
+Here is a very simple example of how to use it:
+
+```typescript
+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 middlware manifest file
+  middlewareInfo: middlewareInfo
+  // If the app should be bundled for cloudflare workers
+  isInCloudflare: true
+})
+```

Diff for: docs/pages/contribute/plugin.mdx

@@ -10,6 +10,12 @@ The easiest way to deploy OpenNext to AWS is with [SST](https://docs.sst.dev/sta
 
 For more information, check out the SST docs: https://docs.sst.dev/start/nextjs
 
+### Ion
+
+You can also deploy OpenNext to AWS using [Ion](https://ion.sst.dev/). 
+
+Check out the [Ion Docs](https://ion.sst.dev/docs/start/nextjs/)
+
 ### Other Frameworks
 
 The OpenNext community has contributed deployment options for a few other frameworks.

Diff for: docs/pages/get_started.mdx

@@ -1,17 +1,31 @@
 import {SITE} from "../config"
+import { Callout } from 'nextra/components'
 
-### Open source Next.js serverless adapter
+<Callout>
+This docs is for the V3 of OpenNext. If you are looking for the V2 docs, you can find them [here](/v2).
+
+If you're migrating from V2 to V3, you can find the migration guide [here](/migration#from-opennext-v2).
+</Callout>
+
+### Open source Next.js adapter
 
 ---
 
-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.
 
+OpenNext takes the Next.js build output and converts it into packages that can be deployed  across a variety of environments. 
+Natively OpenNext has support for AWS Lambda and classic Node Server. It also offer partial support for the `edge` runtime in Cloudflare Workers.
+
+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.
+
+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.
 
 ---
 
 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.
 
-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.
+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.
+
+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.
 
 ---
 
@@ -23,10 +37,6 @@ Closed source SaaS products like [Amplify](https://aws.amazon.com/amplify/) have
 
 ---
 
-The goal of OpenNext is to create an open source, framework agnostic, serverless adapter for Next.js.
-
-OpenNext is currently built for AWS but we plan to support any functions as a service platform.
-
 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).
 ## Features
 
@@ -48,4 +58,5 @@ OpenNext aims to support all Next.js 13 features. Some features are work in prog
 ## Who is using OpenNext?
 
 [NHS England](https://github.com/nhs-england-tools/terraform-aws-opennext),
-[Udacity](https://engineering.udacity.com/deploying-next-js-on-the-edge-with-sst-is-sst-the-game-changer-its-claimed-to-be-1f05a0abc27c)
+[Udacity](https://engineering.udacity.com/deploying-next-js-on-the-edge-with-sst-is-sst-the-game-changer-its-claimed-to-be-1f05a0abc27c)
+[Gymshark UK](https://uk.gymshark.com)

Diff for: docs/pages/index.mdx

@@ -11,11 +11,13 @@ The build output is then transformed into a format that can be deployed to AWS.
 ```bash
 my-next-app/
   .open-next/
-    cache/                         -> ISR cache files to upload to an S3 Bucket
-    assets/                        -> Static files to upload to an S3 Bucket
-    server-function/               -> Handler code for server Lambda Function
-    revalidation-function/         -> Handler code for revalidation Lambda Function
-    image-optimization-function/   -> Handler code for image optimization Lambda Function
-    warmer-function/               -> Cron job code to keep server function warm
-    dynamo-provider/               -> Code for a CDK custom resource to populate a DynamoDB table
+    cache/                         -> ISR cache files to upload - This cannot be directly served
+    assets/                        -> Static files to upload
+    server-functions/
+      default/                     -> Handler code for the default server
+      other-fn/                    -> Handler code for another backend
+    revalidation-function/         -> Handler code for revalidation backend
+    image-optimization-function/   -> Handler code for image optimization backend
+    warmer-function/               -> Cron job code to keep server function warm - Not mandatory
+    dynamo-provider/               -> Code for a custom resource to populate the Tag Cache - Only necessary for app dir
 ```

Diff for: docs/pages/inner_workings.mdx

@@ -1,3 +1,5 @@
 {
-  "isr": "ISR"
-}
+  "caching": "Caching (ISR/SSG)",
+  "components": "Main Components",
+  "architecture": "Default Architecture"
+}