On-demand Rendering Adapters
Astro allows you to choose on-demand rendering for some, or all of your pages and endpoints. This is also known as server-side rendering (SSR): generating HTML pages on the server when requested and sending them to the client. An adapter is used to run your project on the server and handle these requests.
This on-demand rendering allows you to:
- Implement sessions for login state in your app.
- Render data from an API called dynamically with
- Deploy your site to a host using an adapter.
Consider enabling on-demand server rendering 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.
Enable on-demand server renderingSection titled Enable on-demand server rendering
Both of Astro’s on-demand rendering output modes (
hybrid) allow you to take advantage of static site performance by pre-rendering individual routes whenever possible, whether you have an entirely dynamic app or a mostly static site that needs on-demand rendering only for select routes.
To decide which one to use in your project, choose the
output option that represents how most of your pages and routes will be rendered:
output: 'server': On-demand rendered by default. Use this when most or all of your site or app should be server-rendered on request. Any individual page or endpoint can opt-in to pre-rendering.
output: 'hybrid': Pre-rendered to HTML by default. Use this when most of your site should be static. Any individual page or endpoint can opt-out of pre-rendering.
Because the server will need to generate at least some pages on demand, both of these modes require you to add an adapter to carry out the server functions.
Configure Section titled Configure server or hybrid
To enable on-demand rendering, first update your
output configuration to one of the two server-rendered modes.
For example, to configure a highly dynamic app where every page is rendered on demand by default, add
output: 'server' to your Astro config:
You can then choose to override the default on-demand rendering of
server mode on any page or route by exporting
const prerender = true:
Opting-in to pre-rendering in Section titled Opting-in to pre-rendering in server mode
For a mostly server-rendered app configured as
output: server, add
export const prerender = true to any page or route to pre-render a static page or endpoint:
Opting out of pre-rendering in Section titled Opting out of pre-rendering in hybrid mode
For a mostly static site configured as
output: hybrid, add
export const prerender = false to any files that should be server-rendered on demand:
Add an AdapterSection titled Add an Adapter
To deploy a project in
hybrid mode, you also need to add an adapter. This is because both of these modes require a server runtime: the environment that runs code on the server to generate pages when they are requested. Each adapter allows Astro to output a script that runs your project on a specific runtime, such as Vercel, Netlify or Cloudflare.
You can find both official and community adapters in our integrations directory. Choose the one that corresponds to your deployment environment.
Section titled astro add install
astro add install
You can add any of the official adapters maintained by Astro with the following
astro add command. This will install the adapter and make the appropriate changes to your
astro.config.mjs file in one step.
For example, to install the Vercel adapter, run:
Manual InstallSection titled Manual Install
You can also add an adapter manually by installing the package and updating
For example, to install the Vercel adapter manually:
Install the adapter to your project dependencies using your preferred package manager:
Add the adapter to your
astro.config.mjsfile’s import and default export, along with your desired
Note that different adapters may also have different configuration settings. Read each adapter’s documentation, and apply any necessary config options to your chosen adapter in
On-demand rendering featuresSection titled On-demand rendering features
HTML streamingSection titled HTML streaming
With HTML streaming, a document is broken up into chunks, sent over the network in order, and rendered on the page in that order. In
hybrid mode, Astro uses HTML streaming to send each component to the browser as it renders them. This makes sure the user sees your HTML as fast as possible, although network conditions can cause large documents to be downloaded slowly, and waiting for data fetches can block page rendering.
CookiesSection titled Cookies
hybrid modes, a page or API endpoint can check, set, get, and delete cookies.
The example below updates the value of a cookie for a page view counter:
See more details about
Astro.cookies and the
AstroCookie type in the API reference.
Section titled Response
You can also return a Response from any page using on-demand rendering.
The example below returns a 404 on a dynamic page after looking up an id in the database:
Section titled Request
Astro.request is a standard Request object. It can be used to get the
method, and even body of the request.
hybrid mode, you can access additional information from this object for pages that are not statically-generated.
Section titled Astro.request.headers
Section titled Astro.request.method
The HTTP method used in the request is available as
Astro.request.method. This works like the browser’s
Request.method. It returns the string representation of the HTTP method used in the request.
See more details about
Astro.request in the API reference.
Server EndpointsSection titled Server Endpoints
A server endpoint, also known as an API route, is a special function exported from a
.ts file within the
src/pages/ folder. A powerful feature of server-side rendering on demand, API routes are able to securely execute code on the server.
To learn more, see our Endpoints Guide.Learn