From d6b1dd201749d77bf52d3c3f69550b459792f568 Mon Sep 17 00:00:00 2001 From: Dario Piotrowicz Date: Mon, 18 Dec 2023 13:11:09 +0000 Subject: [PATCH 1/5] add gotchas md --- packages/next-on-pages/README.md | 4 +++ packages/next-on-pages/docs/gotchas.md | 35 ++++++++++++++++++++++ packages/next-on-pages/docs/supported.md | 37 ++++-------------------- 3 files changed, 44 insertions(+), 32 deletions(-) create mode 100644 packages/next-on-pages/docs/gotchas.md diff --git a/packages/next-on-pages/README.md b/packages/next-on-pages/README.md index 8143b4871..c032e32ea 100644 --- a/packages/next-on-pages/README.md +++ b/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. diff --git a/packages/next-on-pages/docs/gotchas.md b/packages/next-on-pages/docs/gotchas.md new file mode 100644 index 000000000..4186bfa63 --- /dev/null +++ b/packages/next-on-pages/docs/gotchas.md @@ -0,0 +1,35 @@ +# Gotchas + +## App router + +### `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 Next.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 \ No newline at end of file diff --git a/packages/next-on-pages/docs/supported.md b/packages/next-on-pages/docs/supported.md index 7c02487c3..fa2c42ed6 100644 --- a/packages/next-on-pages/docs/supported.md +++ b/packages/next-on-pages/docs/supported.md @@ -163,40 +163,13 @@ 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` - -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 +For more details see: + - [`generateStaticParams` gotcha](./gotchas.md#generatestaticparams) + - [`getStaticPaths` gotcha](./gotchas.md#getstaticpaths) #### Caching and Data Revalidation From 0b41b82432dd6a5406ed7b9334fda4e3aaaa2624 Mon Sep 17 00:00:00 2001 From: Dario Piotrowicz Date: Mon, 18 Dec 2023 14:38:30 +0000 Subject: [PATCH 2/5] add app not-found gotcha --- packages/next-on-pages/docs/gotchas.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/packages/next-on-pages/docs/gotchas.md b/packages/next-on-pages/docs/gotchas.md index 4186bfa63..d96163423 100644 --- a/packages/next-on-pages/docs/gotchas.md +++ b/packages/next-on-pages/docs/gotchas.md @@ -2,6 +2,23 @@ ## 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 Next.js serverless function (which, as such, is incompatible with `@cloudflare/next-on-pages`). From 56391355c3028737a4b0069a5126ccaec24e53b1 Mon Sep 17 00:00:00 2001 From: Dario Piotrowicz Date: Mon, 18 Dec 2023 14:41:03 +0000 Subject: [PATCH 3/5] run prettier:fix --- packages/next-on-pages/docs/gotchas.md | 4 ++-- packages/next-on-pages/docs/supported.md | 5 +++-- 2 files changed, 5 insertions(+), 4 deletions(-) diff --git a/packages/next-on-pages/docs/gotchas.md b/packages/next-on-pages/docs/gotchas.md index d96163423..a19661e5d 100644 --- a/packages/next-on-pages/docs/gotchas.md +++ b/packages/next-on-pages/docs/gotchas.md @@ -7,6 +7,7 @@ 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'; @@ -33,7 +34,6 @@ In such cases you need to instruct Next.js not to do so by specifying a `false` ### `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): @@ -49,4 +49,4 @@ export async function getStaticPaths() { } ``` -> 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 \ No newline at end of file +> 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 diff --git a/packages/next-on-pages/docs/supported.md b/packages/next-on-pages/docs/supported.md index fa2c42ed6..fb62865b4 100644 --- a/packages/next-on-pages/docs/supported.md +++ b/packages/next-on-pages/docs/supported.md @@ -168,8 +168,9 @@ In case the Vercel build process generates predendered pages for your applicatio `@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. For more details see: - - [`generateStaticParams` gotcha](./gotchas.md#generatestaticparams) - - [`getStaticPaths` gotcha](./gotchas.md#getstaticpaths) + +- [`generateStaticParams` gotcha](./gotchas.md#generatestaticparams) +- [`getStaticPaths` gotcha](./gotchas.md#getstaticpaths) #### Caching and Data Revalidation From 6fa459cd67149986c93187dc76e387f90c30d28e Mon Sep 17 00:00:00 2001 From: Dario Piotrowicz Date: Thu, 21 Dec 2023 23:25:13 +0100 Subject: [PATCH 4/5] apply minor amends --- packages/next-on-pages/docs/gotchas.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/next-on-pages/docs/gotchas.md b/packages/next-on-pages/docs/gotchas.md index a19661e5d..8635dc6bf 100644 --- a/packages/next-on-pages/docs/gotchas.md +++ b/packages/next-on-pages/docs/gotchas.md @@ -6,7 +6,7 @@ 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: +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) @@ -22,7 +22,7 @@ export default async function NotFound() { ### `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 Next.js serverless function (which, as such, is incompatible with `@cloudflare/next-on-pages`). +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): From 3d461a8885b76a58c2cadc8786d100c232067231 Mon Sep 17 00:00:00 2001 From: Dario Piotrowicz Date: Fri, 22 Dec 2023 18:39:16 +0100 Subject: [PATCH 5/5] capitalize 'n' in node.js --- packages/next-on-pages/docs/gotchas.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/packages/next-on-pages/docs/gotchas.md b/packages/next-on-pages/docs/gotchas.md index 8635dc6bf..47f1bd92e 100644 --- a/packages/next-on-pages/docs/gotchas.md +++ b/packages/next-on-pages/docs/gotchas.md @@ -4,7 +4,7 @@ ### 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`). +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: @@ -22,7 +22,7 @@ export default async function NotFound() { ### `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`). +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): @@ -34,7 +34,7 @@ In such cases you need to instruct Next.js not to do so by specifying a `false` ### `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`). +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):