Rendering Modes

Your Astro project code must be rendered to HTML in order to be displayed on the web.

Astro pages, routes, and API endpoints can be either pre-rendered at build time as static pages or rendered on demand by a server when a route is requested. On-demand rendering requires an adapter to execute code on the server, while prerendered pages are served as static HTML.

• output: 'static' (default): Routes are prerendered at build time. You can opt-out of prerendering on any individual route.
• output: 'server' (app mode): All routes are rendered on the server on demand by default. You can opt-in to prerendering on any individual route.

See more about the output setting in the configuration reference.

By default, your entire Astro site will be prerendered, and static HTML pages will be sent to the browser. If you have some pages that require server rendering, for example, a page that checks for cookies and displays personalized content, you can choose to render these individual routes on demand. The rest of your site will be a static site.

For a highly dynamic app, set your build output configuration to server-render all your pages by default. Then, you can choose to prerender any individual pages that do not require a server to execute, such as a privacy policy or about page.

Opting in or out of prerendering

Section titled Opting in or out of prerendering

Both of Astro’s rendering modes allow you to prerender and render on demand in the same project. The only difference is which kind of rendering happens by default.

You can set a prerender value (true or false) in your page route to opt in or out of prerendering and override your output’s default mode.

See more about adding an adapter and using on-demand rendering for some or all of your routes.

Prerendered pages

Section titled Prerendered pages

'static': by default
'server': with export const prerender = true

Prerendered pages are built ahead of time and ready to send to the browser. The same HTML document is sent to the browser for every visitor, and a full-site rebuild is required to update the contents of the page. This method is also known as static site generation (SSG).

By default, all Astro projects are configured to be pre-rendered at build time (statically generated) to provide the most lightweight browser experience. The browser does not need to wait for any HTML to build because the server does not need to generate any pages on demand. Your site is not dependent on the performance of a backend data source, and once built, will remain available to visitors as a static site as long as your server is functioning.

Prerendered pages in Astro can still include Astro features such as:

• Client islands for interactive UI components in an otherwise static, pre-rendered page.
• Server islands for rendering dynamic or personalized content within a static page shell.
• View transitions for client-side routing with animation and state persistence across page navigation.
• Middleware (with some limitations) to intercept and transform response data from a request.

Tip

Astro’s default static mode is a powerful, modern-feeling choice for content-focused sites with the ability to add individual on-demand routes for dynamic or personalized pages when needed.

On-demand rendered routes

Section titled On-demand rendered routes

'static': with export const prerender = false and an adapter
'server': by default, with an adapter

Since on-demand routes are generated per visit, they can be customized for each viewer. For example, a page rendered on demand can show a logged-in user their account information or display freshly updated data without requiring a full-site rebuild. On-demand rendering on the server at request time is also known as server-side rendering (SSR).

Read more about features available with on-demand rendering and an adapter, such as cookies, Response and Request objects, HTML streaming, and more.

You may want to render a route on demand if you need the following:

• API endpoints: Create specific pages that function as API endpoints for tasks like database access, authentication, and authorization while keeping sensitive data hidden from the client.

• Protected pages: Restrict access to a page based on user privileges, by handling user access on the server.

• Frequently changing content: Generate individual pages without requiring a static rebuild of your site. This is useful when the content of a page updates frequently, for example displaying data from an API called dynamically with fetch().

Tip

On-demand server rendering in Astro, especially when combined with view transitions, provides a true app experience without the JavaScript overhead of a client-side, single-page application. Even highly dynamic, interactive apps are possible.