Skip to content
v5-beta

On-demand Rendering

Astro allows you to choose on-demand rendering for some, or all of your pages and endpoints.

Generating HTML pages on the server when requested and sending them to the client is also known as server-side rendering (SSR). An adapter is used to run your project on the server and handle these requests.

Official Adapters

Section titled Official Adapters

Astro maintains official adapters for Node.js, Vercel, Netlify, and Cloudflare.

Find even more community-maintained adapters (e.g. Deno, SST, AWS) in our integrations directory.

SSR Adapters

Add an Adapter

Section titled Add an Adapter

To render any of your pages on demand, for any output mode, you need to add an adapter.

Each adapter allows Astro to output a script that runs your project on a specific runtime: the environment that runs code on the server to generate pages when they are requested (e.g. Netlify, Cloudflare).

You can find both official and community adapters in our integrations directory. Choose the one that corresponds to your deployment environment.

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 Netlify adapter, run:

Terminal window
npx astro add netlify

You can also add an adapter manually by installing the NPM package (e.g. @astrojs/netlify) and updating astro.config.mjs yourself.

Note that different adapters may have different configuration settings. Read each adapter’s documentation, and apply any necessary config options to your chosen adapter in astro.config.mjs

Opting out of prerendering in static mode

Section titled Opting out of prerendering in static mode

For a mostly static site configured as output: static (Astro’s default), add export const prerender = false to any files that should be server-rendered on demand:

src/pages/randomnumber.js
export const prerender = false;


export async function GET() {
  let number = Math.random();
  return new Response(
    JSON.stringify({
      number,
      message: `Here's a random number: ${number}`,
    }),
  );
}

Opting in to prerendering in server mode

Section titled Opting in to prerendering in server mode

With output: server configured, add export const prerender = true to any page or route to prerender a static page or endpoint:

src/pages/mypage.astro
---
export const prerender = true;
// ...
---
<html>
  <!-- Static, pre-rendered page here... -->
</html>
src/pages/mypage.mdx
---
layout: '../layouts/markdown.astro'
title: 'My page'
---
export const prerender = true;


# This is my static, pre-rendered page
src/pages/myendpoint.js
export const prerender = true;


export async function GET() {
  return new Response(
    JSON.stringify({
      message: `This is my static endpoint`,
    }),
  );
}

On-demand rendering features

Section titled On-demand rendering features

HTML streaming

Section 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. Astro uses HTML streaming in on-demand rendering 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.

Related recipe: Using streaming to improve page performance

Cookies

Section titled Cookies

A page or API endpoint rendered on demand can check, set, get, and delete cookies.

The example below updates the value of a cookie for a page view counter:

src/pages/index.astro
---
export const prerender = false; // Not needed in 'server' mode


let counter = 0


if (Astro.cookies.has("counter")) {
  const cookie = Astro.cookies.get("counter")
  counter = cookie.number() + 1
}


Astro.cookies.set("counter",counter)
---
<html>
  <h1>Counter = {counter}</h1>
</html>

See more details about Astro.cookies and the AstroCookie type in the API reference.

Response

Section titled Response

Astro.response is a standard ResponseInit object. It can be used to set the response status and headers.

The example below sets a response status and status text for a product listing page when the product does not exist:

src/pages/my-product.astro
---
export const prerender = false; // Not needed in 'server' mode


import { getProduct } from '../api';


const product = await getProduct(Astro.params.id);


// No product found
if (!product) {
  Astro.response.status = 404;
  Astro.response.statusText = 'Not found';
}
---
<html>
  <!-- Page here... -->
</html>

Astro.response.headers

Section titled Astro.response.headers

You can set headers using the Astro.response.headers object:

src/pages/index.astro
---
export const prerender = false; // Not needed in 'server' mode


Astro.response.headers.set('Cache-Control', 'public, max-age=3600');
---
<html>
  <!-- Page here... -->
</html>

Return a Response object

Section titled Return a Response object

You can also return a Response object directly 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:

src/pages/[id].astro
---
export const prerender = false; // Not needed in 'server' mode


import { getProduct } from '../api';


const product = await getProduct(Astro.params.id);


// No product found
if (!product) {
  return new Response(null, {
    status: 404,
    statusText: 'Not found'
  });
}
---
<html>
  <!-- Page here... -->
</html>

Request

Section titled Request

Astro.request is a standard Request object. It can be used to get the url, headers, method, and even the body of the request.

You can access additional information from this object for pages that are not statically generated.

Astro.request.headers

Section titled Astro.request.headers

The headers for the request are available on Astro.request.headers. This works like the browser’s Request.headers. It is a Headers object where you can retrieve headers such as the cookie.

src/pages/index.astro
---
export const prerender = false; // Not needed in 'server' mode


const cookie = Astro.request.headers.get('cookie');
// ...
---
<html>
  <!-- Page here... -->
</html>

Astro.request.method

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.

src/pages/index.astro
---
export const prerender = false; // Not needed in 'server' mode


console.log(Astro.request.method) // GET (when navigated to in the browser)
---

See more details about Astro.request in the API reference.

Server Endpoints

Section titled Server Endpoints

A server endpoint, also known as an API route, is a special function exported from a .js or .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.

The function takes an endpoint context and returns a Response.

To learn more, see our Endpoints Guide.

Contribute

What’s on your mind?

Create GitHub Issue

Quickest way to alert our team of a problem.

Community