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 ofgetServerSideProps andgetInitialProps in the page.

This feature allows Next.js to emit hybrid applications that containboth server-rendered and statically generated pages.

Good to know: 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 anultra fast loading experience for your users.

How it works

IfgetServerSideProps orgetInitialProps is present in a page, Next.js will switch to render the page on-demand, per-request (meaningServer-Side Rendering).

If the above is not the case, Next.js willstatically optimize your page automatically by prerendering the page to static HTML.

During prerendering, the router'squery object will be empty since we do not havequery information to provide during this phase. After hydration, Next.js will trigger an update to your application to provide the route parameters in thequery object.

The cases where the query will be updated after hydration triggering another render are:

• The page is adynamic-route.
• The page has query values in the URL.
• Rewrites are configured in yournext.config.js since these can have parameters that may need to be parsed and provided in thequery.

To be able to distinguish if the query is fully updated and ready for use, you can leverage theisReady field onnext/router.

Good to know: Parameters added withdynamic routes to a page that's usinggetStaticProps will always be available inside thequery object.

next build will emit.html files for statically optimized pages. For example, the result for the pagepages/about.js would be:

.next/server/pages/about.html

And if you addgetServerSideProps to the page, it will then be JavaScript, like so:

.next/server/pages/about.js

Caveats

• If you have acustomApp withgetInitialProps then this optimization will be turned off in pages withoutStatic Generation.
• If you have acustomDocument withgetInitialProps be sure you check ifctx.req is defined before assuming the page is server-side rendered.ctx.req will beundefined for pages that are prerendered.
• Avoid using theasPath value onnext/router in the rendering tree until the router'sisReady field istrue. Statically optimized pages only knowasPath on the client and not the server, so using it as a prop may lead to mismatch errors. Theactive-class-name example demonstrates one way to useasPath as a prop.