Deploying Astro Sites
Island architecture SSG/SSR with zero JS by default, deploy to Vercel, Netlify, Cloudflare, or static hosts.
PlatformsIntermediate
Why
Astro's island architecture ships zero JavaScript by default and hydrates only interactive components, producing the fastest possible static sites. It integrates React/Vue/Svelte components selectively for interactivity.
Platform-as-a-Service adoption grew 24% in 2024 as teams shift from VM management to git-push deploys. the cloud infrastructure market reached $330B in 2024, growing 22% year-over-year (Synergy Research), and PaaS layers capture the majority of new workloads.
When
Use Astro for content-heavy sites (blogs, docs, marketing) where speed is paramount. Add SSR adapter when dynamic content or user sessions are needed.
How
1. Build — npm run build outputs dist/ (static) or .vercel/.netlify (adapter)
2. Static deploy — upload dist/ to any CDN, no server needed
3. Vercel — npx astro add vercel, auto-configures SSR + edge
4. Netlify — npx astro add netlify, serverless functions
5. Cloudflare — npx astro add cloudflare, runs on Workers
6. Node — npx astro add node, run node ./dist/server/entry.mjs
7. Hydration — client:load, client:visible, client:idle directives
8. Integrations — add React/Vue/Svelte/Tailwind selectively
Example
// astro.config.mjs — Vercel adapter + React islands
import { defineConfig } from "astro/config";
import vercel from "@astrojs/vercel";
import react from "@astrojs/react";
export default defineConfig({
adapter: vercel(),
integrations: [react()],
output: "hybrid", // static + selective SSR
});
// src/pages/index.astro — island hydration
---
import Counter from "../components/Counter.jsx";
---
<html><body>
<h1>Static HTML, zero JS</h1>
<Counter client:visible /> {/* hydrates only when visible */}
</body></html>
// Static-only deploy (no adapter)
// npm run build → dist/ → upload to any CDN
Common Problems
- ⚠Island not hydrating — forgot client: directive, component stays static
- ⚠SSR endpoint 404 on static host — output: 'static' but using server-side code, switch to 'hybrid'
- ⚠React/Vue component conflicts — multiple framework integrations with shared state issues
Best Practices
- ✓Default to client:idle or client:visible — avoid client:load unless the component is above-the-fold critical
- ✓Use output: 'static' when possible — only add an adapter when you genuinely need SSR endpoints
- ✓Set up health checks and graceful shutdown — handle SIGTERM to drain in-flight requests before exit