Server-Side Rendering Runtime

Relevant source files

• examples/advanced-routing/astro.config.mjs
• examples/advanced-routing/src/fetch.ts
• examples/component/tsconfig.json
• examples/container-with-vitest/tsconfig.json
• packages/astro/e2e/astro-island-hydration-error.test.ts
• packages/astro/e2e/fixtures/pass-js/src/components/React.tsx
• packages/astro/e2e/fixtures/pass-js/src/pages/index.astro
• packages/astro/src/actions/consts.ts
• packages/astro/src/actions/vite-plugin-actions.ts
• packages/astro/src/container/index.ts
• packages/astro/src/container/pipeline.ts
• packages/astro/src/core/app/base.ts
• packages/astro/src/core/app/dev/app.ts
• packages/astro/src/core/app/entrypoints/virtual/dev.ts
• packages/astro/src/core/app/pipeline.ts
• packages/astro/src/core/app/prepare-response.ts
• packages/astro/src/core/app/types.ts
• packages/astro/src/core/base-pipeline.ts
• packages/astro/src/core/build/generate.ts
• packages/astro/src/core/build/pipeline.ts
• packages/astro/src/core/build/plugins/plugin-manifest.ts
• packages/astro/src/core/build/plugins/plugin-ssr.ts
• packages/astro/src/core/config/schemas/base.ts
• packages/astro/src/core/constants.ts
• packages/astro/src/core/errors/errors-data.ts
• packages/astro/src/core/fetch/fetch-state.ts
• packages/astro/src/core/fetch/index.ts
• packages/astro/src/core/fetch/types.ts
• packages/astro/src/core/fetch/vite-plugin.ts
• packages/astro/src/core/hono/index.ts
• packages/astro/src/core/i18n/domain.ts
• packages/astro/src/core/i18n/handler.ts
• packages/astro/src/core/logger/load.ts
• packages/astro/src/core/middleware/astro-middleware.ts
• packages/astro/src/core/middleware/noop-middleware.ts
• packages/astro/src/core/pages/handler.ts
• packages/astro/src/core/routing/handler.ts
• packages/astro/src/core/routing/rewrite.ts
• packages/astro/src/manifest/serialized.ts
• packages/astro/src/runtime/client/idle.ts
• packages/astro/src/runtime/client/load.ts
• packages/astro/src/runtime/client/media.ts
• packages/astro/src/runtime/client/only.ts
• packages/astro/src/runtime/client/visible.ts
• packages/astro/src/runtime/server/astro-island.ts
• packages/astro/src/runtime/server/hydration.ts
• packages/astro/src/runtime/server/index.ts
• packages/astro/src/runtime/server/jsx.ts
• packages/astro/src/runtime/server/render/any.ts
• packages/astro/src/runtime/server/render/astro/factory.ts
• packages/astro/src/runtime/server/render/astro/instance.ts
• packages/astro/src/runtime/server/render/astro/render-template.ts
• packages/astro/src/runtime/server/render/astro/render.ts
• packages/astro/src/runtime/server/render/common.ts
• packages/astro/src/runtime/server/render/component.ts
• packages/astro/src/runtime/server/render/dom.ts
• packages/astro/src/runtime/server/render/head-propagation/runtime.ts
• packages/astro/src/runtime/server/render/head.ts
• packages/astro/src/runtime/server/render/index.ts
• packages/astro/src/runtime/server/render/instruction.ts
• packages/astro/src/runtime/server/render/page.ts
• packages/astro/src/runtime/server/render/slot.ts
• packages/astro/src/runtime/server/render/util.ts
• packages/astro/src/runtime/server/scripts.ts
• packages/astro/src/runtime/server/serialize.ts
• packages/astro/src/runtime/server/util.ts
• packages/astro/src/types/public/config.ts
• packages/astro/src/types/public/internal.ts
• packages/astro/src/vite-plugin-app/app.ts
• packages/astro/src/vite-plugin-app/createAstroServerApp.ts
• packages/astro/src/vite-plugin-astro-server/plugin.ts
• packages/astro/test/astro-scripts.test.ts
• packages/astro/test/fixtures/astro-scripts/src/components/ScriptWithContent.astro
• packages/astro/test/fixtures/astro-scripts/src/components/SlotRenderWrapper.astro
• packages/astro/test/fixtures/astro-scripts/src/pages/slot-render-script-position.astro
• packages/astro/test/fixtures/parallel/package.json
• packages/astro/test/fixtures/parallel/src/components/Delayed.astro
• packages/astro/test/fixtures/parallel/src/pages/index.astro
• packages/astro/test/units/actions/actions-hmr.test.ts
• packages/astro/test/units/app/astro-attrs.test.ts
• packages/astro/test/units/app/dev-url-construction.test.ts
• packages/astro/test/units/app/headers.test.ts
• packages/astro/test/units/app/logger.test.ts
• packages/astro/test/units/app/prerender-allowed-domains.test.ts
• packages/astro/test/units/app/test-helpers.ts
• packages/astro/test/units/app/url-attribute-xss.test.ts
• packages/astro/test/units/assets/image-layout.test.ts
• packages/astro/test/units/fetch/index.test.ts
• packages/astro/test/units/fetch/provider-finalize.test.ts
• packages/astro/test/units/hono/index.test.ts
• packages/astro/test/units/i18n/domain.test.ts
• packages/astro/test/units/i18n/i18n-app.test.ts
• packages/astro/test/units/logger/load.test.ts
• packages/astro/test/units/render/class-list-and-style.test.ts
• packages/astro/test/units/render/head-propagation/runtime-adapters.test.ts
• packages/astro/test/units/render/head-propagation/runtime.test.ts
• packages/astro/test/units/render/html-primitives.test.ts
• packages/astro/test/units/render/hydration.test.ts
• packages/astro/test/units/render/jsx-custom-elements.test.ts
• packages/astro/test/units/routing/origin-pathname.test.ts
• packages/astro/test/units/routing/routing-helpers.test.ts
• packages/astro/test/units/server-islands/server-islands-render.test.ts
• packages/astro/test/units/test-utils.ts
• reference/handlers.md
• scripts/cmd/build.js
• scripts/cmd/prebuild.js
• scripts/smoke/check.js

Purpose and Scope

The Server-Side Rendering (SSR) Runtime in Astro is responsible for processing every incoming HTTP request into a fully rendered HTTP response. This involves a structured pipeline that includes middleware execution, component rendering, and response generation, while abstracting away environment-specific details for adaptability across Node.js, Deno, and edge environments.

This page offers an in-depth technical overview of key runtime abstractions—RenderContext, SSRResult, and SSRManifest—and details the entire request processing pipeline, covering middleware orchestration, component rendering (including hydration and JSX rendering), slot and head management, and the flexible handler pipeline system.

Sources: packages/astro/src/core/app/types.ts63-148 packages/astro/src/core/base-pipeline.ts67-120

---

Request Processing Architecture

The SSR runtime architecture is organized into multiple interconnected layers, progressing from receiving the raw HTTP request to producing the final HTTP response.

Request Processing Flow

• The FetchState class encapsulates the state for an individual request, including cookies, locals, and route parameters packages/astro/src/core/fetch/fetch-state.ts129-176
• The SSRManifest provides static application configuration used for route matching, assets, and renderers packages/astro/src/core/app/types.ts63-148
• Middleware is executed as a chain, enabling instrumentation, request modification, and response short-circuiting packages/astro/src/core/base-pipeline.ts126-194
• SSRResult manages the hydration, styling, and scripting metadata during rendering packages/astro/src/types/public/internal.ts11-15
• The final HTTP response is constructed after rendering completes via renderPage packages/astro/src/runtime/server/render/page.ts12-131

Sources: packages/astro/src/runtime/server/render/page.ts12-131 packages/astro/src/core/fetch/fetch-state.ts129-176 packages/astro/src/core/base-pipeline.ts126-194

---

Core Runtime Objects

FetchState and Pipeline

Astro's SSR runtime is divided between static application configuration (the Pipeline) and per-request orchestration (the FetchState).

• Pipeline holds immutable configuration for the app:

  • manifest: SSRManifest — the manifest generated at build time containing routes, assets, etc packages/astro/src/core/app/types.ts63-148
  • renderers: SSRLoadedRenderer[] — array of framework renderers (React, Vue, Solid, etc.) packages/astro/src/types/public/internal.ts13
  • middleware — composed middleware chain to run for each request packages/astro/src/core/app/types.ts106

• FetchState manages the current request lifecycle:

  • request — the standard Request object for the incoming HTTP request packages/astro/src/core/fetch/fetch-state.ts135
  • routeData — metadata about the matched route packages/astro/src/core/fetch/fetch-state.ts136
  • locals — per-request state shared across middleware and rendering phases packages/astro/src/core/fetch/fetch-state.ts85
  • cookies — parsed cookie interface for reading/modifying HTTP cookies packages/astro/src/core/fetch/fetch-state.ts83

Sources: packages/astro/src/core/fetch/fetch-state.ts73-176 packages/astro/src/core/app/types.ts63-148

---

SSRResult

SSRResult is the rendering context object responsible for collecting and managing all metadata related to rendering a single page. It is passed deeply through the render tree as components render.

Key responsibilities:

• Accumulate stylesheets and inline styles used by components packages/astro/src/core/app/types.ts28-30
• Track scripts needed for hydration or interactivity packages/astro/src/core/app/types.ts32-35
• Store hydration metadata for client-side islands packages/astro/src/runtime/server/render/component.ts89-106
• Manage head elements collected during rendering packages/astro/src/runtime/server/render/page.ts63-68

Sources: packages/astro/src/runtime/server/render/component.ts89-106 packages/astro/src/runtime/server/render/page.ts63-68

---

SSRManifest

The SSRManifest is a static object loaded once at server startup (or bundled at build time). It includes:

• Routes and routing rules (routes) packages/astro/src/core/app/types.ts65
• Framework renderers (renderers) packages/astro/src/core/app/types.ts79
• Static assets and CSS (assets, inlinedScripts) packages/astro/src/core/app/types.ts98-99
• CSP (Content Security Policy) configuration (csp) packages/astro/src/core/app/types.ts125
• i18n domain data and locale information (i18n) packages/astro/src/core/app/types.ts105

Sources: packages/astro/src/core/app/types.ts63-148

---

Component Rendering System

Astro supports native Astro components, framework components (React, Vue, etc.), and raw HTML/Server Islands.

Framework Component Hydration and Islands

Astro implements an island architecture that allows framework components to be hydrated on the client.

• Renderer Selection: The runtime calls the check hook on configured renderers to find one that can handle the component packages/astro/src/runtime/server/render/component.ts132-137
• Directives: extractDirectives parses client:* attributes to determine the hydration strategy packages/astro/src/runtime/server/render/component.ts94-97
• Hydration: If a client: directive is present, metadata is populated to inject the <astro-island> custom element and its corresponding hydration script packages/astro/src/runtime/server/render/component.ts101-106

Sources: packages/astro/src/runtime/server/render/component.ts75-192 packages/astro/src/runtime/server/hydration.ts10-11

---

Page Rendering Modes

The runtime supports several rendering strategies in renderPage:

Mode	Implementation	Description
Streaming (Node.js)	renderToAsyncIterable	Yields chunks of HTML as an AsyncIterable for Node.js response construction packages/astro/src/runtime/server/render/page.ts75-85
Streaming (Web)	renderToReadableStream	Uses ReadableStream for Deno/Edge environments packages/astro/src/runtime/server/render/page.ts87
Buffered	renderToString	Renders the entire page into a string before sending packages/astro/src/runtime/server/render/page.ts90

Sources: packages/astro/src/runtime/server/render/page.ts71-91

---

Server Island Architecture

Server Islands provide deferred rendering for components marked with server:defer.

• Directives: containsServerDirective identifies components that should be deferred packages/astro/src/runtime/server/render/component.ts28
• Instructions: The runtime uses RenderInstruction to propagate metadata about deferred islands up the tree packages/astro/src/runtime/server/render/instruction.ts1-5
• Boundaries: templateEnter and templateExit track nesting depth during rendering to manage scoped content packages/astro/src/runtime/server/index.ts46

Sources: packages/astro/src/runtime/server/render/component.ts28 packages/astro/src/runtime/server/render/server-islands.ts1-28

---

JSX Rendering and Slot Management

• JSX: Components are rendered via renderJSX, which associates components with their specific renderers packages/astro/src/runtime/server/index.ts15
• Slots: Managed via renderSlot and renderSlots. Slots are merged using mergeSlots to handle multiple children passed to a component packages/astro/src/runtime/server/index.ts52-63
• Static Slots: The runtime handles <astro-slot> and <astro-static-slot> for efficient HTML output packages/astro/src/runtime/server/render/component.ts67-73

Sources: packages/astro/src/runtime/server/index.ts52-63 packages/astro/src/runtime/server/render/slot.ts1-30

---

Head Management

Astro manages the <head> section by buffering content:

• Detection: The runtime checks if a page component contains a <head> in its tree (headInTree) packages/astro/src/runtime/server/render/page.ts61-64
• Injection: If no head is found, Astro can implicitly inject one. renderHead and maybeRenderHead are used to flush buffered head content into the HTML stream packages/astro/src/runtime/server/index.ts28-31
• Propagation: Routes on a "propagation path" (e.g., layouts) block the head flush until async slots are ready packages/astro/src/runtime/server/render/page.ts65-68

Sources: packages/astro/src/runtime/server/render/page.ts61-68 packages/astro/src/runtime/server/render/head.ts1-10

---

Handler Pipeline and Middleware

The request lifecycle is governed by a pipeline that coordinates middleware and response generation:

• Middleware Chain: Composed middleware executes before the final page handler. It can modify locals or return a Response early packages/astro/src/core/base-pipeline.ts126-194
• Dev Server Pipeline: In development, Vite middleware (baseMiddleware, trailingSlashMiddleware, routeGuardMiddleware) is injected into the stack to handle assets and routing before the Astro SSR handler packages/astro/src/vite-plugin-astro-server/plugin.ts121-138
• Error Handling: recordServerError and setRouteError capture runtime failures and format them for the Astro error overlay in dev mode packages/astro/src/vite-plugin-astro-server/plugin.ts93-98

Sources: packages/astro/src/vite-plugin-astro-server/plugin.ts78-105 packages/astro/src/core/base-pipeline.ts126-194