Automatic Static Optimization
Next.js automatically determines that a page is static (can be prerendered) if it has no blocking data requirements. This determination is made by the absence of
getInitialProps in the page.
This feature allows Next.js to emit hybrid applications that contain both server-rendered and statically generated pages.
Statically generated pages are still reactive: Next.js will hydrate your application client-side to give it full interactivity.
One of the main benefits of this feature is that optimized pages require no server-side computation, and can be instantly streamed to the end-user from multiple CDN locations. The result is an ultra fast loading experience for your users.
How it works
getInitialProps is present in a page, Next.js will switch to render the page on-demand, per-request (meaning Server-Side Rendering).
If the above is not the case, Next.js will statically optimize your page automatically by prerendering the page to static HTML.
During prerendering, the router's
query object will be empty since we do not have
query information to provide during this phase. After hydration, Next.js will trigger an update to your application to provide the route parameters in the
The cases where the query will be updated after hydration triggering another render are:
- The page is a dynamic-route.
- The page has query values in the URL.
- Rewrites are configured in your
next.config.jssince these can have parameters that may need to be parsed and provided in the
To be able to distinguish if the query is fully updated and ready for use, you can leverage the
isReady field on
Note: Parameters added with dynamic routes to a page that's using
getStaticPropswill always be available inside the
next build will emit
.html files for statically optimized pages. For example, the result for the page
pages/about.js would be:
And if you add
- If you have a custom
getInitialPropsthen this optimization will be turned off in pages without Static Generation.
- If you have a custom
getInitialPropsbe sure you check if
ctx.reqis defined before assuming the page is server-side rendered.
undefinedfor pages that are prerendered.
- Avoid using the
next/routerin the rendering tree until the router's
true. Statically optimized pages only know
asPathon the client and not the server, so using it as a prop may lead to mismatch errors. The
active-class-nameexample demonstrates one way to use
asPathas a prop.