Skip to content

Astro integrations, build and deploy

An Astro project becomes a website in three steps: you extend it with integrations, build it into a folder of files (or a server bundle), and put that output on a host. This page covers those steps for Astro 7, using the invented OrdersPortal docs site from the introduction and pages and content pages.

Package versions were checked on npm at the time of writing: astro 7.4.12, @astrojs/mdx 8.1.6, @astrojs/sitemap 3.7.5, @astrojs/react 7.1.9, @astrojs/preact 6.1.6 and @astrojs/node 11.1.13. The Preact integration was installed and used for the island sample on the previous page; the configuration and CI fragments on this page follow the Astro docs and were not deployed from here.

Topic What it covers
Integrations Adding frameworks, MDX, sitemap and other features with astro add
Build and preview astro build, the dist/ folder, site and base, astro preview
Deploying a static site GitHub Pages with the official action, Azure Static Web Apps, other hosts
On-demand rendering Adapters, prerender, output: 'server', server islands and caching

Integrations extend Astro: UI framework renderers (React, Preact, Vue, Svelte, Solid, Alpine), content formats (MDX, Markdoc), build features (sitemap, Partytown) and deployment adapters. Official integrations are installed with astro add, which installs a compatible version, adds it to integrations in astro.config.mjs and adjusts tsconfig.json where needed. You can name several at once. Community integrations are listed in the Astro integrations directory; check whether each supports astro add or needs manual setup.

Some features that used to be integrations are now built in: image optimization is astro:assets (<Image /> and <Picture />), so the old @astrojs/image package is deprecated and must not be installed; view transitions use <ClientRouter /> from astro:transitions; fonts and Content Security Policy are configuration options.

Terminal window
# Add React for islands, MDX for components in Markdown, and a sitemap
npx astro add react mdx sitemap
// astro.config.mjs after astro add (fragment)
// @ts-check
import { defineConfig } from 'astro/config';
import react from '@astrojs/react';
import mdx from '@astrojs/mdx';
import sitemap from '@astrojs/sitemap';
export default defineConfig({
site: 'https://docs.example.test', // required by @astrojs/sitemap for absolute URLs
integrations: [react(), mdx(), sitemap()],
});

The same pattern, with preact(), ran on Astro 7.4.12 for the island sample on the previous page. Upgrade Astro and every official integration together with npx @astrojs/upgrade, so their versions stay compatible.

Pitfalls:

  • Installing @astrojs/image. It was removed in Astro 3 and is deprecated on npm; use astro:assets.
  • Mismatched majors. An integration built for Astro 6 may not load on Astro 7; @astrojs/upgrade updates them together.
  • Two JSX frameworks without include. With React and Preact (or Solid) in one project, tell each integration which files are its own with the include option, or components render with the wrong runtime.

npm run build runs astro build. With the default static output, every page is prerendered to HTML in dist/, together with hashed CSS and JavaScript in dist/_astro/, processed images, and everything from public/ copied as-is. npm run preview (astro preview) serves dist/ locally so you can check the production output before deploying; it is not a production server.

Two configuration values matter for every deployment. site is the full public URL, used for canonical links, the sitemap and RSS. base is the path prefix when the site is not served from the domain root, such as /orders-portal-docs on a GitHub Pages project site; links must then include it (import.meta.env.BASE_URL). trailingSlash and build.format control whether pages build to about/index.html (the default, directory) or about.html (file), which should match how your host resolves URLs.

Terminal window
# Typical local release check (fragment)
npx astro check # type-check .astro and .ts files
npm run build # astro build -> dist/
npm run preview # serves dist/ on http://localhost:4321

For the sample project, the prerendered output is dist/index.html, dist/status/index.html, dist/support/index.html, one dist/releases/<id>/index.html per release entry and dist/robots.txt, following the default directory build format.

Pitfalls:

  • Missing site. The sitemap integration needs it and canonical URLs fall back to relative paths without it.
  • Hard-coded root links with a base. href="/status" breaks on https://example.test/orders-portal-docs/; build links from import.meta.env.BASE_URL.
  • Testing with astro dev only. The dev server is more forgiving than the production build; preview the built output, and run a link checker against it, before you deploy.

A static Astro build is a folder of files, so any static host works: GitHub Pages, Azure Static Web Apps, Netlify, Vercel, Cloudflare, Firebase Hosting, or object storage behind a CDN such as Amazon S3 with CloudFront. Hosts that build from Git usually detect Astro and use npm run build with dist as the output directory. The Astro docs keep a deployment guide per host.

For GitHub Pages, Astro maintains the withastro/action GitHub Action, which detects your package manager from the lockfile, installs, builds and uploads dist/; actions/deploy-pages then publishes it. Set site to your github.io URL and base to /<repository> unless the repository is named <user>.github.io. Enable GitHub Actions as the Pages source in the repository settings.

# .github/workflows/deploy.yml (fragment, from the Astro GitHub Pages guide)
name: Deploy to GitHub Pages
on:
push:
branches: [ main ]
workflow_dispatch:
permissions:
contents: read
pages: write
id-token: write
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
- uses: withastro/action@v6 # node-version defaults to 24
deploy:
needs: build
runs-on: ubuntu-latest
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
steps:
- id: deployment
uses: actions/deploy-pages@v5

For Azure Static Web Apps, create the app from the Azure portal or the VS Code extension and point it at the repository; the generated GitHub Actions workflow builds the site and uploads dist (set the app location to the project folder and the output location to dist). Custom domains and certificates are covered in Azure Static Web Apps custom domain configuration.

Pitfalls:

  • Deep links that 404. Static hosts serve /releases/v2-0/ from releases/v2-0/index.html; if your host expects .html files, switch build.format to file instead of adding rewrite rules.
  • No custom 404 page. Add src/pages/404.astro; most hosts serve 404.html automatically, GitHub Pages included.
  • Building with an unsupported Node.js on the host. Astro 7.4.2 and later need Node.js 22.23.4 or later; set the host’s Node.js version explicitly instead of relying on its default.

By default Astro prerenders every page. To render some routes per request (personalized pages, cookies, form handling, live data), install an adapter for your runtime: Astro maintains official adapters for Node.js, Netlify, Vercel and Cloudflare, and the community maintains more. Then add export const prerender = false to the pages or endpoints that must run on the server; everything else stays static. If most of the site is dynamic, set output: 'server' to make on-demand the default and mark static pages with export const prerender = true. The old hybrid output mode is gone since Astro 5; static output plus per-route opt-out replaces it.

An adapter also enables server islands (server:defer on a component), and Astro 7 makes route caching stable: set a cache provider and routeRules (such as maxAge and swr per route pattern) in the config, or control caching per request with Astro.cache.

// astro.config.mjs (fragment): Node.js adapter in standalone mode
import { defineConfig } from 'astro/config';
import node from '@astrojs/node';
export default defineConfig({
site: 'https://docs.example.test',
adapter: node({ mode: 'standalone' }),
// output: 'server', // only if most routes are dynamic
});
---
// src/pages/status.astro: now rendered per request (fragment)
export const prerender = false;
const status = await fetch('https://api.example.test/status').then((r) => r.json());
---
<h1>{status.service}: {status.healthy ? 'healthy' : 'degraded'}</h1>
Terminal window
npx astro add node # installs @astrojs/node and sets the adapter
npm run build # static pages in dist/client, server in dist/server
HOST=0.0.0.0 PORT=4321 node ./dist/server/entry.mjs

In standalone mode the Node.js server serves both the static files and the on-demand routes; in middleware mode it exports a handler for Express or Fastify instead.

Pitfalls:

  • Setting output: 'server' without need. It turns every page into server work; for a docs or marketing site, one or two opted-out routes are cheaper and faster.
  • Reading cookies or headers on a prerendered page. At build time there is no request; the values are empty and the result is baked into HTML for everyone.
  • Deploying an adapter build to a static host. An on-demand route needs a runtime; a static host serves only the prerendered files and returns 404 for the rest.
  • Content that changes when you publish: static output on any static host, deployed from CI.
  • A few personalized or live routes: keep static output, add an adapter and prerender = false on those routes, or use server islands.
  • An application-like site: output: 'server' with the adapter for your platform, plus route caching.

What does astro add do beyond npm install? It installs a version of the integration compatible with your Astro version, adds it to the integrations (or adapter) setting in astro.config.mjs, and updates related configuration such as tsconfig.json, so the project works without manual edits.

Why do site and base matter for GitHub Pages? site gives Astro the absolute URL for canonical links and the sitemap. A project site lives under /<repository>/, so base must be set for asset and page URLs to resolve; links in your own code must use import.meta.env.BASE_URL.

How do you make one page dynamic in an otherwise static Astro site? Add an adapter for the host’s runtime and put export const prerender = false in that page. The rest of the site stays prerendered; only that route runs on the server.

What replaced the hybrid output mode? Since Astro 5, the default static output allows per-route opt-out with prerender = false once an adapter is installed, which covers what hybrid did.

Senior scenario: OrdersPortal’s docs must show each customer’s contract tier in the header, but the docs should stay fast and cheap to host. What do you propose? Keep every docs page prerendered and cacheable at the CDN. Render the tier badge as a server island (server:defer) behind an adapter, so the static shell is served instantly and the personalized fragment is fetched separately with the user’s cookie; give it a fallback slot. Cache the island response per user briefly or not at all, and keep the rest under long-lived CDN caching. This avoids moving the whole site to output: 'server' and keeps personalized data out of shared caches.