Server rendering in Astro

This chapter follows Islands and client directives in Astro.

Static pages are fast and cheap to host, but they are the same for every visitor and only change when you rebuild. A login page, a search results page, or a form that writes to a database needs code that runs per request. Astro lets you add that route by route instead of turning the whole site into a server application.

Prerendered and on-demand routes

Astro has two output modes, and both allow mixing:

Pick the mode that matches most of your routes. A content site keeps static and marks the few dynamic pages; an application uses server and marks the marketing pages as prerendered.

1
---
2
export const prerender = false;
3

4
const user = Astro.cookies.get('user')?.value;
5
if (!user) return Astro.redirect('/login/');
6
---
7
<h1>Welcome back, {user}</h1>

An on-demand dynamic route such as src/pages/products/[id].astro does not need getStaticPaths; Astro.params.id comes from the request URL and the page can look the product up at request time.

Adapters

On-demand routes need a runtime to answer requests. An adapter builds the server part of your site for a specific host:

1
npx astro add node
2
npx astro add cloudflare
3
npx astro add vercel
4
npx astro add netlify

@astrojs/node produces a standalone Node.js server or middleware for an existing one. The hosting adapters produce functions in the format each platform expects. Prerendered routes are still emitted as static files and served without invoking the server. This knowledgebase has no adapter: every page is prerendered, so the build output is plain files.

Request data, cookies, and responses

Inside an on-demand page or endpoint, the Astro global exposes the request:

1
---
2
export const prerender = false;
3

4
const query = Astro.url.searchParams.get('q') ?? '';
5
const results = query ? await searchArticles(query) : [];
6
if (query && results.length === 0) Astro.response.status = 404;
7
---
8
<form><input name="q" value={query} /></form>
9
<p>{results.length} results</p>

In a prerendered page these values reflect the build, not a visitor: there are no request headers or cookies at build time.

Middleware

src/middleware.ts runs before every route is rendered. It can read and modify the request, short-circuit with a response, and pass data to pages through context.locals:

1
import { defineMiddleware, sequence } from 'astro:middleware';
2

3
const auth = defineMiddleware(async (context, next) => {
4
  const token = context.cookies.get('session')?.value;
5
  context.locals.user = token ? await lookupUser(token) : null;
6
  if (context.url.pathname.startsWith('/admin/') && !context.locals.user) {
7
    return context.redirect('/login/');
8
  }
9
  return next();
10
});
11

12
const timing = defineMiddleware(async (_context, next) => {
13
  const started = performance.now();
14
  const response = await next();
15
  response.headers.set('Server-Timing', `render;dur=${performance.now() - started}`);
16
  return response;
17
});
18

19
export const onRequest = sequence(auth, timing);

Type locals once in src/env.d.ts by extending App.Locals, and every page reading Astro.locals.user is checked. Middleware also runs for prerendered pages during the build, which is useful for shared setup but means request-specific logic only matters for on-demand routes.

Actions

Actions are type-safe server functions with input validation, callable from forms and from client code. Define them in src/actions/index.ts:

1
import { defineAction } from 'astro:actions';
2
import { z } from 'astro/zod';
3

4
export const server = {
5
  subscribe: defineAction({
6
    accept: 'form',
7
    input: z.object({
8
      email: z.string().email(),
9
    }),
10
    handler: async ({ email }) => {
11
      await addSubscriber(email);
12
      return { email };
13
    },
14
  }),
15
};

An HTML form can post to the action directly, which works without any client JavaScript:

1
---
2
import { actions } from 'astro:actions';
3
export const prerender = false;
4

5
const result = Astro.getActionResult(actions.subscribe);
6
---
7
{result?.data && <p>Subscribed {result.data.email}</p>}
8
{result?.error && <p>Please enter a valid email address.</p>}
9
<form method="POST" action={actions.subscribe}>
10
  <input type="email" name="email" required />
11
  <button>Subscribe</button>
12
</form>

From an island, call await actions.subscribe(formData) and receive { data, error }; isInputError(error) tells validation failures apart from other errors. Actions replace most hand-written API endpoints, because validation and types are shared between caller and server.

Environment variables

import.meta.env works as in Vite: variables prefixed PUBLIC_ are exposed to client code, everything else stays on the server. For validated, typed variables, declare a schema with envField:

1
import { defineConfig, envField } from 'astro/config';
2

3
export default defineConfig({
4
  env: {
5
    schema: {
6
      API_URL: envField.string({ context: 'client', access: 'public' }),
7
      API_SECRET: envField.string({ context: 'server', access: 'secret' }),
8
    },
9
  },
10
});

Read them from astro:env/client or astro:env/server. Astro fails the build when a required variable is missing, and refuses to import a secret into client code.

Choosing static or on demand

Prerender everything that is the same for all visitors, even pages that change daily; a scheduled rebuild is cheaper and faster than rendering per request. Use on-demand rendering when the response depends on the visitor or the request: authentication, personalized data, search parameters, and form submissions. For a mostly static page with one personal fragment, reach for a server island before making the whole page dynamic.

This is the last chapter in the Astro series. For a compact reference, see the Astro cheat sheet.