From 5b893663fdb3658de4e8ce2bb5966fbfe4e905ef Mon Sep 17 00:00:00 2001 From: idkwhojamesis <43428092+idkwhojamesis@users.noreply.github.com> Date: Sat, 21 May 2022 19:45:47 -0700 Subject: [PATCH] Include router.asPath caveats in docs (#36876) initial commit Co-authored-by: JJ Kasper --- docs/advanced-features/automatic-static-optimization.md | 1 + docs/api-reference/next/router.md | 2 ++ 2 files changed, 3 insertions(+) diff --git a/docs/advanced-features/automatic-static-optimization.md b/docs/advanced-features/automatic-static-optimization.md index 8780102d7a671..465086c099e1f 100644 --- a/docs/advanced-features/automatic-static-optimization.md +++ b/docs/advanced-features/automatic-static-optimization.md @@ -46,3 +46,4 @@ And if you add `getServerSideProps` to the page, it will then be JavaScript, lik - If you have a [custom `App`](/docs/advanced-features/custom-app.md) with `getInitialProps` then this optimization will be turned off in pages without [Static Generation](/docs/basic-features/data-fetching/get-static-props.md). - If you have a [custom `Document`](/docs/advanced-features/custom-document.md) with `getInitialProps` be sure you check if `ctx.req` is defined before assuming the page is server-side rendered. `ctx.req` will be `undefined` for pages that are prerendered. +- Avoid using the `asPath` value on [`next/router`](/docs/api-reference/next/router.md#router-object) in the rendering tree until the router's `isReady` field is `true`. Statically optimized pages only know `asPath` on the client and not the server, so using it as a prop may lead to mismatch errors. The `active-class-name` example demonstrates one way to use `asPath` as a prop. diff --git a/docs/api-reference/next/router.md b/docs/api-reference/next/router.md index ac0ba94ab4ce6..f0806f4b68529 100644 --- a/docs/api-reference/next/router.md +++ b/docs/api-reference/next/router.md @@ -53,6 +53,8 @@ The following is the definition of the `router` object returned by both [`useRou - `isReady`: `boolean` - Whether the router fields are updated client-side and ready for use. Should only be used inside of `useEffect` methods and not for conditionally rendering on the server. See related docs for use case with [automatically statically optimized pages](/docs/advanced-features/automatic-static-optimization.md) - `isPreview`: `boolean` - Whether the application is currently in [preview mode](/docs/advanced-features/preview-mode.md). +> Using the `asPath` field may lead to a mismatch between client and server if the page is rendered using server-side rendering or [automatic static optimization](/docs/advanced-features/automatic-static-optimization.md). Avoid using `asPath` until the `isReady` field is `true`. + The following methods are included inside `router`: ### router.push