Endpoints

Purpose and Scope

Astro endpoints are page-like modules that return Response objects instead of rendering HTML components. In user projects, they are commonly used for generated JSON, XML, images, RSS feeds, and API routes. The official authoring model is simple: place a .js or .ts file under src/pages, export an HTTP method such as GET, and return a web-standard Response. During a static build, Astro calls matching endpoints to emit files. In server output, the same shape becomes a live route that runs for each request.

This page focuses on the practical endpoint contract and on the repository signals that support build-time generation and response correctness. The supplied source paths show two important sides of that contract. First, packages such as @astrojs/rss and astro-prism are built from TypeScript source into distributable packages that can participate in generated output workflows. Second, Astro’s own build infrastructure for font assets creates stable identifiers and resolved URLs, which is the same general kind of work endpoint authors perform when they turn project data into public files. Sources: packages/astro-rss/tsconfig.build.json, packages/astro-prism/tsconfig.build.json, packages/astro/src/assets/fonts/infra/build-font-file-id-generator.ts, packages/astro/src/assets/fonts/infra/build-url-resolver.ts

Relevant Source Files

• .changeset/sharp-bags-build.md — records a build correctness fix for prerendered pages in Cloudflare workerd, emphasizing that rendering and response streaming errors must surface as build failures instead of silently producing truncated output.
• configs/tsconfig.build.json — defines the shared package build TypeScript configuration, including rootDir, outDir, build-info placement, and src inclusion for packages that ship endpoint-adjacent utilities.
• packages/astro-prism/tsconfig.build.json — shows a package-specific build configuration extending the shared build config and including both source files and virtual.d.ts.
• packages/astro-rss/tsconfig.build.json — shows @astrojs/rss using the shared build configuration, relevant because RSS is one of the canonical endpoint outputs in Astro projects.
• packages/astro/src/assets/fonts/infra/build-font-file-id-generator.ts — implements deterministic build-time font file IDs by hashing resolved file content and appending the font type.
• packages/astro/src/assets/fonts/infra/build-url-resolver.ts — implements build-time URL resolution for asset output, including base paths, asset prefixes, search parameters, content-security-policy resources, and collected URLs.

Endpoint Authoring Model

A static file endpoint is named for the output file it should create. For example, src/pages/data.json.ts produces /data.json, and src/pages/sitemap.xml.ts produces /sitemap.xml. The extension before .ts or .js matters because Astro removes the module extension during the build. The exported function receives a context object with request and route information, and the return value is a Response. TypeScript users can annotate the export with APIRoute or use satisfies APIRoute to keep the handler aligned with Astro’s expected endpoint shape.

// src/pages/builtwith.json.ts
import type { APIRoute } from 'astro';
 
export const GET = (() => {
  return new Response(
    JSON.stringify({ name: 'Astro', url: 'https://astro.build/' }),
    { headers: { 'content-type': 'application/json' } },
  );
}) satisfies APIRoute;

For binary output, the endpoint still returns a Response; the body can be an ArrayBuffer, stream, or another web-response body type. This matters because endpoints are not limited to text APIs. They can generate image files, feed documents, metadata files, or other build artifacts as long as the response body and headers describe the file correctly. The font asset utilities in Astro’s source demonstrate similar build-time output concerns: stable identifiers are generated from resolved content, and final URLs are assembled from base paths, asset prefixes, and search parameters. Sources: packages/astro/src/assets/fonts/infra/build-font-file-id-generator.ts, packages/astro/src/assets/fonts/infra/build-url-resolver.ts

Static Build versus Server Routes

The most important endpoint distinction is when the handler executes. In a statically generated site, Astro invokes custom endpoints during astro build and writes their response bodies to the output directory. This is ideal for content that can be known at build time, such as an RSS feed, a generated JSON index, or an image fetched and transformed during the build. The shared TypeScript build configuration in this repository reinforces that published packages are compiled from src to dist, keeping package implementation code separated from emitted artifacts. Sources: configs/tsconfig.build.json, packages/astro-rss/tsconfig.build.json

In server output, endpoint modules become request-time API routes. They can inspect the incoming Request, use route params, and return different responses per request. The public pattern is intentionally close to the web platform, so endpoint code reads like standard Fetch API code rather than framework-specific controller code. You can also call an endpoint function from server-side Astro code by importing the method and passing the current Astro context, which is useful when a page needs data from a route handler without making an extra network fetch.

// src/pages/api/hello.ts
import type { APIRoute } from 'astro';
 
export const GET: APIRoute = () => {
  return new Response(JSON.stringify({ greeting: 'Hello' }));
};

Build-Time Output and URL Resolution

Endpoint authors often need deterministic public URLs: an RSS route needs a stable feed path, an image endpoint needs a meaningful filename, and generated assets may need cacheable names. BuildFontFileIdGenerator shows the repository’s build-time pattern for stable file identities. It accepts a hasher and a content resolver, resolves the original URL to content, hashes that resolved content, and appends the font type. The result is an ID tied to file contents rather than only to the original URL, which is the safer model for generated artifacts that should change when their source changes. Sources: packages/astro/src/assets/fonts/infra/build-font-file-id-generator.ts

BuildUrlResolver shows the complementary step: once an ID exists, Astro must turn it into a URL that respects project configuration. The resolver checks whether an asset prefix applies to the file extension, joins the prefix, base path, and generated ID, preserves adapter-level search parameters, and records both the final URL and content-security-policy resources. Endpoint code usually does not instantiate this class directly, but the behavior illustrates the same deployment constraints endpoint authors should consider: base paths, CDN prefixes, query parameters added by adapters, and CSP-safe resource origins. Sources: packages/astro/src/assets/fonts/infra/build-url-resolver.ts

Response Correctness and Failure Signals

Because static endpoints run during the build, response failures must be reported as build failures. The Cloudflare changeset captures this expectation clearly: when prerendered pages throw during rendering in workerd, streaming errors should not be swallowed, astro build should not exit successfully, and truncated HTML should not be emitted. The fix buffers the response body inside workerd before sending it back to the build process so that streaming failures are caught and surfaced with clear error messages. Endpoint authors should treat thrown errors, rejected promises, and invalid response bodies as build-blocking problems in static output. Sources: .changeset/sharp-bags-build.md

The same principle applies to generated feeds and other endpoint-like artifacts. A route that writes incomplete XML, omits required headers, or hides an upstream fetch failure can produce output that appears valid to the build tool but fails for consumers. Use explicit status codes, content-type headers, and defensive error handling. For build-only endpoints, prefer failing loudly over returning partial data. For server endpoints, return appropriate 4xx or 5xx responses and keep sensitive diagnostic information out of the public body.

Compact Reference

Next Steps

When adding an endpoint, start from the file name and execution mode. If the route should become a file, include the desired output extension before .ts or .js and make the handler deterministic at build time. If the route should behave like an API, enable server output and design the handler around request-time inputs. Then check deployment details: base paths, asset prefixes, caching headers, and whether any adapter adds search parameters or response handling constraints. For adjacent topics, read the pages on routing, RSS feeds, server-side rendering and adapters, actions, and image and asset handling.