Astro framework: complete guide

The web framework that prioritises performance by shipping zero JavaScript by default

9 min

Astro is a modern web framework that builds fast sites by design. Its philosophy is radical: ship zero JavaScript to the browser by default, hydrating interactive components only when necessary. The result is pages that load instantly, with perfect Core Web Vitals scores.

Created in 2021 by Fred K. Schott and the team behind Snowpack, Astro has grown to become the preferred choice for content sites, documentation, marketing and blogs. This guide covers its architecture, key features and when to choose it over alternatives like Next.js or Nuxt.

Islands architecture: the foundation of Astro

The islands architecture is the central concept of Astro. Each page is rendered as static HTML, and only the components that need interactivity (a carousel, a form, a menu) are hydrated with JavaScript. The rest of the page remains as pure HTML, with zero JavaScript cost.

This contrasts with SPA frameworks like React or Vue, where the entire page is hydrated with JavaScript even though 90% of the content is static. In Astro, a blog with an interactive comment section only ships JavaScript for the comment component, not for the entire article.

  • Static HTML by default, JavaScript only where needed
  • Hydration directives: client:load, client:visible, client:idle, client:media
  • Each island hydrates independently without blocking global rendering
  • Compatible with React, Vue, Svelte, Preact, Solid and Lit in the same project

Content Collections and data management

Astro includes a native Content Collections system that lets you define, validate and query local content (Markdown, MDX, JSON, YAML) with typed schemas using Zod. Each collection has its schema, and Astro generates TypeScript types automatically.

For headless projects, Astro integrates with any CMS that exposes an API: Strapi, Contentful, Sanity, WordPress (REST/GraphQL), Directus. Data is fetched at build time (SSG) or request time (SSR) depending on each route’s configuration.

  • Typed schemas with Zod for automatic content validation
  • Automatic TypeScript type generation for each collection
  • Native Markdown and MDX support with embedded components
  • Loader API to connect with external data sources (CMS, databases)

SSR, SSG and hybrid rendering

Astro supports three rendering modes: static (SSG), server (SSR) and hybrid. In static mode, all pages are pre-rendered at build time and served from a CDN. In server mode, pages are generated on each request. In hybrid mode, each route can choose its own strategy.

For content sites with infrequent updates, SSG offers the best performance and lowest hosting costs. For routes that require personalisation, authentication or real-time data, SSR is the right choice. Astro allows combining both in the same project without complex configuration.

Performance in practice

Astro produces the highest Lighthouse scores among major frameworks. A typical Astro site scores 100/100 on Performance with pages weighing less than 50KB of HTML and zero KB of JavaScript (except for interactive islands). First Contentful Paint (FCP) and Largest Contentful Paint (LCP) times are under 1 second in most cases.

Built-in image optimisation (astro:assets) automatically generates modern formats (WebP, AVIF), multiple sizes and lazy loading. Fonts, styles and scripts are automatically optimised with per-component scoped CSS and dead code elimination.

Ecosystem and integrations

Astro has a growing catalogue of official and community integrations: Tailwind CSS, MDX, Sitemap, RSS, React, Vue, Svelte, Partytown (for third-party scripts), and deploy adapters for Node.js, Vercel, Netlify, Cloudflare and Deno.

Integration with UI frameworks is a key differentiator: you can use React components for one interactive widget, Vue for another, and Svelte for a third, all on the same Astro page. Each framework is only loaded where it is used, without penalising overall performance.

  • Adapters: Node.js, Vercel, Netlify, Cloudflare, Deno
  • UI frameworks: React, Vue, Svelte, Preact, Solid, Lit
  • Utilities: Tailwind CSS, MDX, Sitemap, RSS, Partytown
  • CMS: integrations with Contentful, Strapi, Sanity, WordPress, Storyblok

When to choose Astro

Astro is the optimal choice for sites where content is the star: blogs, documentation, corporate websites, portfolios, landing pages and marketing sites. It also works well for ecommerce with medium-sized catalogues where performance is critical.

It is not the best option for highly interactive web applications (dashboards, editors, collaborative tools) where most of the interface requires hydration. For those cases, Next.js or Remix offer a rendering model better suited to the volume of interactivity.

  • Ideal: blogs, docs, corporate websites, marketing, content ecommerce
  • Suitable: ecommerce with medium catalogues, interactive portfolios
  • Less suitable: dashboards, SaaS apps, editors, collaborative tools

Key Takeaways

  • Astro ships zero JavaScript by default and only hydrates the components that need it
  • Islands architecture combines static performance with selective interactivity
  • Content Collections with Zod offer typed and validated content management
  • SSG, SSR and hybrid in the same project without complex configuration
  • Ideal for content sites; less suitable for highly interactive applications

Is Astro the right framework for your project?

We help you evaluate whether Astro fits your requirements and build a fast, optimised and easy-to-maintain site.