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.
Topics on this page
Section titled “Topics on this page”| 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
Section titled “Integrations”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.
# Add React for islands, MDX for components in Markdown, and a sitemapnpx astro add react mdx sitemap// astro.config.mjs after astro add (fragment)// @ts-checkimport { 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; useastro:assets. - Mismatched majors. An integration built for Astro 6 may not load on Astro 7;
@astrojs/upgradeupdates 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 theincludeoption, or components render with the wrong runtime.
Build and preview
Section titled “Build and preview”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.
# Typical local release check (fragment)npx astro check # type-check .astro and .ts filesnpm run build # astro build -> dist/npm run preview # serves dist/ on http://localhost:4321For 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 onhttps://example.test/orders-portal-docs/; build links fromimport.meta.env.BASE_URL. - Testing with
astro devonly. The dev server is more forgiving than the production build; preview the built output, and run a link checker against it, before you deploy.
Deploying a static site
Section titled “Deploying a static site”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@v5For 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/fromreleases/v2-0/index.html; if your host expects.htmlfiles, switchbuild.formattofileinstead of adding rewrite rules. - No custom 404 page. Add
src/pages/404.astro; most hosts serve404.htmlautomatically, 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.
On-demand rendering
Section titled “On-demand rendering”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 modeimport { 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>npx astro add node # installs @astrojs/node and sets the adapternpm run build # static pages in dist/client, server in dist/serverHOST=0.0.0.0 PORT=4321 node ./dist/server/entry.mjsIn 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.
Choosing between them
Section titled “Choosing between them”- 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 = falseon those routes, or use server islands. - An application-like site:
output: 'server'with the adapter for your platform, plus route caching.
Interview questions
Section titled “Interview questions”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.
Related pages
Section titled “Related pages”- Astro introduction, setup and project structure
- Pages, layouts and content
- Static websites overview and static site generators compared
- Website hosting: custom domains and certificates
Official references
Section titled “Official references”- Integrations guide and astro add (Astro docs)
- CLI reference: astro build, preview and check
- Configuration reference: site, base, build.format, output
- Deploy your Astro site, GitHub Pages and Microsoft Azure
- On-demand rendering and server islands
- Route caching
- @astrojs/node adapter
- Upgrade to Astro v7