Include router.asPath caveats in docs (#36876)

initial commit

Co-authored-by: JJ Kasper <jj@jjsweb.site>

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.

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