9 min read
JavaScript frameworks have spent the last decade getting better at building dynamic applications. Astro took a different path by focusing specifically on sites where content does the heavy lifting, using an architecture that strips JavaScript out of pages unless a component explicitly needs it.
This guide covers how Astro works under the hood, where it fits alongside frameworks like Next.js and Nuxt, and how to deploy Astro projects on Vercel.
Link to headingWhat is Astro?
Astro is a JavaScript web framework for content-driven websites like blogs, documentation portals, marketing pages, and e-commerce storefronts. The compiler generates static HTML on the server and only includes client-side JavaScript when a specific component opts into hydration through a client: directive.
Most JavaScript frameworks assume your site will need a runtime in the browser to handle state, interactions, and dynamic UI updates. That makes sense for dashboards and tools where nearly everything on screen is interactive, but content sites work differently. A blog post is mostly text and images. The interactive parts, a newsletter signup form or a comment section, are small islands on an otherwise static page. Astro was built on that premise: content-heavy pages don't need an application runtime in the browser.
Link to headingHow Astro evolved from static site generators
Fred K. Schott created Astro to bridge the gap between older static site generators and full client-rendered component frameworks. Earlier generators locked you into specific templating languages, and Gatsby brought React's component model to static sites but shipped the React runtime even for pages with no interactivity. Astro took a different approach by letting you author components in React, Vue, or Svelte while producing zero-JavaScript output by default. The project grew steadily from there, and Cloudflare acquired the Astro team in January 2026. The framework remains open source under the MIT License with support for multiple deployment targets.
Link to headingHow Astro works under the hood
Astro's build and delivery model centers on three ideas: island architecture isolates JavaScript to specific components, a zero-JavaScript default ships everything else as pure HTML, and a server-first rendering model controls whether pages are prerendered at build time or generated per request.
Link to headingIsland architecture and partial hydration explained
The island architecture pattern, coined by Katie Sylor-Miller at Etsy and documented by Jason Miller, renders full HTML pages on the server and identifies specific regions that need interactivity. Those regions become "islands" that hydrate independently in the browser, while everything else stays as static HTML.
Astro provides client: directives that control when each component hydrates:
client:load: Hydrates immediately on page load.
client:idle: Hydrates once the browser is idle.
client:visible: Hydrates when the component scrolls into view.
client:media: Hydrates when a CSS media query matches.
client:only: Skips server rendering entirely and hydrates only in the browser.
A carousel using client:visible won't load its JavaScript until the user scrolls to it, while a static navigation bar with no directive ships zero JavaScript regardless of how many React components render it.
Link to headingZero JavaScript by default
This behavior comes from the compiler, not from runtime optimization. Astro renders UI components to HTML and CSS, stripping out client-side JavaScript unless a client: directive requests hydration. A React component without a client: directive executes at build time, emits static HTML, and the React runtime never reaches the browser.
The tradeoff: any component that needs interactivity requires an explicit directive. Frameworks with a built-in runtime handle this automatically, so Astro asks you to make hydration decisions that other tools abstract away.
Link to headingServer-first rendering with SSG, SSR, and hybrid mode
Astro offers static and server output modes. In static mode, all pages are prerendered at build time, and individual routes opt into server-side rendering by adding export const prerender = false. The server mode flips the default, so all pages render on demand.
Astro v5 merged the previous hybrid mode into static. The current release, Astro 6 (March 2026), rebuilt the dev server on Vite's Environment API and added Content Security Policy support while keeping the same per-route rendering control.
Link to headingKey features of Astro
Because each island hydrates independently and bundles its own framework runtime, Astro can support multi-framework projects, type-safe content management, filesystem routing, and browser-native page transitions within the same build.
Link to headingUse React, Vue, Svelte, or Solid in the same project
Official integrations support React, Vue, Svelte, Solid, Preact, and Alpine.js within a single project. You can adopt a new framework incrementally and convert components one at a time without a full rewrite.
Cross-island state sharing requires an external store like Nano Stores rather than a shared component tree, which adds complexity compared to frameworks that use a single runtime.
Link to headingContent collections for structured Markdown and MDX
Content Collections provide type-safe, schema-validated content management for Markdown, MDX, and external data sources. You define schemas using Zod, and Astro enforces them at build time. A blog post missing a required title or pubDate field produces a build error rather than a silent runtime failure.
Astro 6 stabilized live content collections, which were experimental since Astro 5.10, and pull content from external sources at request time rather than only at build time. This lets you integrate headless CMS or API data through the same collections API you use for local Markdown files.
Link to headingFile-based routing and layouts
Astro's routing maps directly to the filesystem. A file at src/pages/about.astro produces the /about route, and src/pages/blog/[slug].astro handles dynamic segments. Layout components define shared page shells once and compose into pages via Astro's slot system, keeping route files focused on content rather than repeated scaffolding.
Link to headingView transitions and page animations
The browser-native View Transitions API landed in Astro 3.0, adding animations between page navigations in a multi-page application with built-in fade, slide, and none options. Astro provides fallback support for browsers that don't yet implement the API natively.
Link to headingWhen to use Astro (and when not to)
Astro's architecture targets a specific type of project, and the boundaries are worth understanding before choosing it over a full-stack framework.
Link to headingCommon use cases for Astro
Astro works well when most of a page is static and only a few components need interactivity:
Blogs and editorial sites: Primarily read-only content, where interactive elements like comment sections or newsletter forms are isolated to specific components.
Marketing sites and landing pages: Mostly static with a few interactive CTAs.
Documentation portals: Large page counts with interactivity limited to search and code copy buttons. Astro's first-party Starlight theme includes search, sidebar navigation, and versioning.
E-commerce storefronts: Mostly static product pages, with only the cart or checkout requiring interactivity.
Portfolio sites: Driven by visual presentation rather than client-side application logic.
In each case, most of the page is static HTML that doesn't need JavaScript in the browser.
Link to headingWhen a different framework is the better choice
Some projects need capabilities that work against Astro's grain. Highly interactive dashboards with persistent state across data tables, charts, and real-time polling are a good example, because the island isolation model means sharing state between components requires external stores rather than a single component tree.
Real-time collaborative apps and complex authenticated SPAs run into the same problem. Full-stack frameworks like Next.js with unified component trees, built-in server-side auth patterns, and a mature ecosystem of data fetching and state management tools are a better fit for these projects.
Link to headingAstro vs. Next.js vs. Gatsby vs. Nuxt
The four frameworks target different points on the spectrum between static content and full-stack interactivity. This table summarizes where each one sits.
Link to headingHow rendering philosophy shapes the developer experience
Astro assumes most websites are content-first and don't need a full application runtime, while Next.js provides the flexibility of a full React framework with SSR, SSG, PPR, and client rendering all available within the same project. Next.js gives teams the most room to grow as requirements change, since a project that starts as a static marketing site can evolve into a full-stack application without switching frameworks.
Astro supports multiple frontend frameworks in the same project, while Next.js and Nuxt are tied to React and Vue, respectively. Nuxt provides a comparable experience for Vue teams, and Gatsby is no longer under active feature development after Netlify acquired the project in 2023, though it still receives occasional maintenance patches.
Link to headingPerformance defaults and bundle size tradeoffs
Astro's compiler strips out all client-side JavaScript unless a client: directive explicitly requests hydration. A marketing site built with Astro can ship zero JavaScript to the browser, while that same site built with Next.js or Gatsby will include the React runtime.
That difference is most visible on content-heavy pages with no interactivity. On pages where most components are interactive, the zero-JavaScript default provides less benefit because each component needs an explicit hydration directive, and Next.js or Nuxt handle that use case with less configuration.
Link to headingDeploying content-driven sites on Vercel
Vercel is framework-agnostic, with first-class support for Astro alongside Next.js, Nuxt, SvelteKit, and other frameworks. Whichever framework best fits your project, you get the same deployment pipeline and platform features without being locked into a single choice.
If you've chosen Astro for a content-focused project, Vercel provides automatic framework detection, preview deployments on every branch push, global caching for static assets, and server-side rendering through Vercel Functions. The same infrastructure that powers every framework on Vercel applies to your Astro project.
Link to headingShip your content site with the right framework on Vercel
Choosing the right framework depends on where your project sits between static content and full-stack interactivity. Astro's island architecture is one approach for content-heavy sites, while Next.js covers a broader range from static pages to complex applications. Vercel supports both, along with Nuxt, SvelteKit, and other frameworks, so the platform doesn't lock you into a single choice.
Vercel handles the build pipeline, preview deployments, and global distribution regardless of which framework you choose. Start a new project on Vercel to deploy with the framework that fits your project.
Link to headingFrequently asked questions about Astro
Link to headingIs Astro only for static sites?
Static output is the default, but Astro supports SSR, dynamic routes, and adapter-based deployment through its server output mode. You can opt individual routes into server-side rendering with a single line of code when they need it.
Link to headingCan I use React or Vue components inside Astro?
Astro supports React, Vue, Svelte, Solid, Preact, and Alpine.js through official integrations. Each component renders to static HTML by default, and adding a client: directive like client:load or client:visible makes it interactive in the browser. You can mix frameworks on the same page, though cross-framework state sharing requires an external store like Nano Stores.
Link to headingHow does Astro handle SEO compared to other frameworks?
Pages are pre-rendered to complete HTML with zero client-side JavaScript by default, so search engine crawlers receive full page content without executing JavaScript. The official @astrojs/sitemap integration auto-generates sitemap XML. Other frameworks like Next.js also pre-render HTML by default and produce crawler-friendly output, so the SEO difference between frameworks depends more on implementation than architecture.
Link to headingWhat is island architecture and how does partial hydration work?
Island architecture renders full HTML pages on the server and identifies interactive regions as "islands" that hydrate independently in the browser. Everything outside those islands stays as static HTML with no JavaScript, and each island loads in parallel, so a lightweight header component becomes interactive without waiting for heavier components elsewhere on the page.