Skip to content

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 or rendered on demand by a server when a route is requested. With Astro islands, you can also include some client-side rendering when necessary.

In Astro, most of the processing occurs on the server, instead of in the browser. This generally makes your site or app faster than client-side rendering when viewed on less-powerful devices or on slower internet connections. Server-rendered HTML is fast, SEO friendly, and accessible by default.

Server output modes

Section titled Server output modes

You can configure how your pages are rendered in your output configuration.

Pre-rendered

Section titled Pre-rendered

The default rendering mode is output: 'static', which creates the HTML for all your page routes at build time.

In this mode, your entire site will be pre-rendered and the server will have all pages 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.

Static sites can include Astro islands for interactive UI components (or even entire embedded client-side rendered apps!) written in the UI framework of your choice in an otherwise static, pre-rendered page.

Astro’s View Transitions API are also available in static mode for animation and state persistence across page navigation. Static sites can also use middleware to intercept and transform response data from a request.

On-demand rendered

Section titled On-demand rendered

Astro’s other two output modes can be configured to enable on-demand rendering of some or all of your pages, routes or API endpoints:

  • output: 'server' for highly dynamic sites with most or all on-demand routes.
  • output: 'hybrid' for mostly static sites with some on-demand routes.

Since they are generated per visit, these routes 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).

Consider enabling server or hybrid mode in your Astro project 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().

Both server and hybrid output modes allow you to include Astro islands for interactivity (or even entire embedded client-side rendered apps!) in your choice of UI frameworks. With middleware and Astro’s View Transitions API for animations and preserving state across route navigations, even highly interactive apps are possible.