Add gotchas documentation (#599)

packages/next-on-pages/README.md

@@ -96,6 +96,10 @@ Running `npx @cloudflare/next-on-pages --help` will display a useful help messag
 
 To see some examples on how to use Next.js features with `@cloudflare/next-on-pages`, see the [Examples document](https://github.com/cloudflare/next-on-pages/blob/main/packages/next-on-pages/docs/examples.md).
 
+## Gotchas
+
+There are a few gotchas that might trip developers over, please familiarize yourself with the [Gotchas document](https://github.com/cloudflare/next-on-pages/blob/main/packages/next-on-pages/docs/gotchas.md) in order to avoid such pitfalls.
+
 ## More Information
 
 For more information on the project please check out the [README](https://github.com/cloudflare/next-on-pages/blob/main/README.md) in the next-on-pages github repository.

packages/next-on-pages/docs/gotchas.md

@@ -0,0 +1,52 @@
+# Gotchas
+
+## App router
+
+### Not found
+
+Next.js generates a not-found route for your application under the hood during the build process. In some circumstances Next.js can detect that the route requires server side logic (particularly if computation is being performed in the root layout component) and it might create a Node.js serverless function (which, as such, is incompatible with `@cloudflare/next-on-pages`).
+
+To prevent such problem we recommend to always provide a custom not-found route which explicitly opts in the edge runtime:
+
+```ts
+// file: (src/)app/not-found.(jsx|tsx)
+export const runtime = 'edge';
+
+export default async function NotFound() {
+    // ...
+    return (
+        // ...
+    );
+}
+```
+
+### `generateStaticParams`
+
+When doing static site generation (SSG) in the app directory and using the [`generateStaticParams`](https://nextjs.org/docs/app/api-reference/functions/generate-static-params) utility, Next.js by default tries to handle requests for non statically generated routes on-demand. It does so by creating a Node.js serverless function (which, as such, is incompatible with `@cloudflare/next-on-pages`).
+
+In such cases you need to instruct Next.js not to do so by specifying a `false` [`dynamicParams`](https://nextjs.org/docs/app/api-reference/file-conventions/route-segment-config#dynamicparams):
+
+```diff
++ export const dynamicParams = false;
+```
+
+## Pages router
+
+### `getStaticPaths`
+
+When doing static site generation (SSG) in the pages directory and using the [`getStaticPaths`](https://nextjs.org/docs/pages/api-reference/functions/get-static-paths) utility, Next.js by default tries to handle requests for non statically generated routes on-demand. It does so by creating a Node.js serverless function (which, as such, is incompatible with `@cloudflare/next-on-pages`).
+
+In such cases you need to instruct Next.js not to do so by specifying a [false `fallback`](https://nextjs.org/docs/pages/api-reference/functions/get-static-paths#fallback-false):
+
+```diff
+export async function getStaticPaths() {
+    // ...
+
+    return {
+        paths,
++       fallback: false,
+	};
+}
+```
+
+> Note that the `paths` array cannot be empty as that causes Next.js to ignore the provided `fallback` value, so make sure that at build time at least one entry is present in the array

packages/next-on-pages/docs/supported.md

@@ -163,40 +163,14 @@ ISR pages are built by the Vercel CLI to generate Vercel [Prerender Functions](h
 
 In case the Vercel build process generates predendered pages for your application, `@cloudflare/next-on-pages` will use static fallback files that are generated by the build process so that your application will still correctly serve your ISR/prerendered pages (but without the regeneration aspect).
 
-#### Statically Generated Routes Edge Cases
+#### Dynamic handling of static routes
 
-Next.js performs a form of static analysis on routes to determine whether they can be [statically generated](https://nextjs.org/docs/app/building-your-application/rendering/static-and-dynamic-rendering), or if they need to be dynamically rendered at request time. In most cases, `@cloudflare/next-on-pages` can handle these pages fine. However, there are some edge cases where this is not possible with pages that have dynamic parameters.
+`@cloudflare/next-on-pages` supports standard statically generated routes, it does however not support dynamic on-demand handling of such routes. Such behavior is not supported because Next.js implements it via Node.js serverless functions, which, as mentioned above are fundamentally incompatible with the Cloudflare network.
 
-##### `generateStaticParams`
+For more details see:
 
-When doing static site generation (SSG) in the app directory, you need to indicate in each page that it is not possible for non-prerendered dynamic routes to occur, i.e. [they should return a 404 response](https://nextjs.org/docs/app/api-reference/file-conventions/route-segment-config#dynamicparams). This is so that the Vercel build process doesn't generate a Node.js serverless function for the dynamic parameter, while generating prerendered HTML files for all params provided by `generateStaticParams` instead.
-
-```diff
-+ export const dynamicParams = false;
-```
-
-##### `getStaticPaths`
-
-In the pages directory, when doing static site generation (SSG), there is a similar scenario as the app dir `generateStaticParams` one. Because of how ISR functions work, you need to indicate that the page [should return a 404 response](https://nextjs.org/docs/pages/api-reference/functions/get-static-paths#fallback-false) for non-prerendered dynamic routes. This is done by setting `fallback: false` in `getStaticPaths`.
-
-```diff
-export async function getStaticPaths() {
-	const res = await fetch('https://.../posts');
-	const posts = await res.json();
-
-	// Get the paths we want to pre-render based on posts
-	const paths = posts.map(post => ({ params: { id: post.id } }));
-
-	// We'll pre-render only these paths at build time.
-	// { fallback: false } means other routes should 404.
-	return {
-		paths,
-+		fallback: false,
-	};
-}
-```
-
-> Note that the `paths` array cannot be empty as that causes Next.js to ignore the provided `fallback` value, so make sure that at build time at least one entry is present in the array
+- [`generateStaticParams` gotcha](./gotchas.md#generatestaticparams)
+- [`getStaticPaths` gotcha](./gotchas.md#getstaticpaths)
 
 #### Caching and Data Revalidation