withastro/astro

Render context

RenderContext is the single object that represents an in-flight Astro request. It is constructed once per request, lives for the duration of that request, and hands a Response back when it's done.

Purpose

Hold per-request state (URL, locals, cookies, session, matched route, params), execute middleware, run the page or endpoint, and produce a Response. It exists in dev, in build (for prerender), and in prod (inside adapters), so a regression in this code path tends to affect every mode at once.

Key file

packages/astro/src/core/render-context.ts — 1,016 lines, the single most critical request-handling file in the framework.

Inputs

class RenderContext {
  constructor(
    public pipeline: Pipeline, // process-wide config + manifest
    public request: Request, // standard Web Request
    public routeData: RouteData, // matched route
    public params: Record<string, string>, // extracted URL params
    public locals: App.Locals, // mutable per-request bag
    public cookies: AstroCookies // typed cookies API
    // ...
  ) {}
}

Pipeline is one of DevPipeline, BuildPipeline, or AppPipeline. All three implement the abstract base in packages/astro/src/core/base-pipeline.ts.

Lifecycle

sequenceDiagram
    participant H as HTTP layer (Vite middleware / adapter / build loop)
    participant RC as RenderContext
    participant MW as Middleware chain
    participant P as Page or Endpoint
    participant R as Renderer

    H->>RC: new RenderContext(pipeline, req, route, …)
    RC->>RC: parse URL, build APIContext
    RC->>MW: run middleware sequence
    MW->>P: next(context)
    P->>R: renderToString / Response
    R-->>P: HTML or Response
    P-->>MW: Response
    MW-->>RC: Response (after onRequest postlude)
    RC-->>H: Response

The next() value passed to middleware is essentially a thunk that invokes the next middleware (or the page), so the chain has the same shape Express users will recognize.

What RenderContext does

Decodes the URL, validates params, derives Astro.url, Astro.site, Astro.generator.
Builds APIContext/AstroGlobal — the same object exposed as context in endpoints and Astro in .astro files. Public types: astro/types.
Runs the middleware chain — packages/astro/src/core/middleware/sequence.ts and callMiddleware.ts.
Resolves the page module — through pipeline.getPageModule(), which abstracts dev (Vite SSR), build (compiled module on disk), and prod (preloaded bundle).
Calls the page or endpoint:
- For pages, hands the resolved component to the framework renderer.
- For endpoints, dispatches by HTTP method (GET, POST, …).
Streams the response via core/render/'s helpers (paginate, slots, ssr-element).
Writes cookies back into the response headers.
Renders error pages when an exception is thrown.

Locals

context.locals is the standard cross-cutting per-request bag. Middleware writes; pages and endpoints read. Type: App.Locals (a global interface users augment).

Cookies

AstroCookies (packages/astro/src/core/cookies/) implements a typed read/write API on top of Set-Cookie. It supports get, set, delete, has, signed cookies, and integration with sessions (see features / sessions).

Sessions

context.session is provided when a session driver is configured (packages/astro/src/core/session/). The runtime is a thin getter — actual storage is plug-pluggable.

CSP

Content Security Policy generation is wired into RenderContext so each rendered page gets a fresh nonce. See features / CSP.

Streaming

Astro renders pages as ReadableStreams when possible. The streaming logic in packages/astro/src/runtime/server/render/ cooperates with RenderContext to flush headers, then write body chunks, then finalize. Adapters that don't support streaming get a Response with a complete body collected in-memory.

Entry points for modification

Add per-request state: extend RenderContext directly (and the public types at packages/astro/src/types/public/context.ts).
Hook the middleware sequence: core/middleware/.
Change how endpoints dispatch: search for routeIsEndpoint and dispatchEndpoint in render-context.ts.

Built by Factory AutoWiki from public repository content. It is a generated preview for codebase exploration, not source-maintained documentation.