Introduction to Astro

Nov 13, 2021updated Jul 18, 2026

An introduction to Astro, the content-driven Web framework that renders HTML, adds JavaScript through islands, and supports static or on-demand routes.

~~~

Astro is a Web framework designed for content-driven sites.

It renders components to HTML and sends no client-side JavaScript by default. When a part of the page needs interactivity, you can add JavaScript only to that component.

This makes Astro a good fit for blogs, documentation, marketing sites, portfolios, and content-heavy stores.

Astro is static by default, not static-only

By default, Astro prerenders every page at build time. The result is a directory of static files that you can deploy to any static host.

Astro can also render selected routes on demand. This is useful for pages that depend on cookies, authentication, or frequently changing data.

On-demand rendering requires an adapter for the platform where the server code will run. The official Astro rendering guide explains the current static and server options.

My advice is to start with the static default. Add on-demand rendering only to routes that need it.

HTML first, JavaScript only where needed

An Astro component renders to HTML with no client-side runtime.

You can use .astro components, plain HTML, Markdown, and MDX. You can also add components from React, Vue, Svelte, Solid, and other supported UI libraries.

Framework components render to HTML by default too. To make one interactive in the browser, add a client:* directive:

---
import Counter from '../components/Counter.jsx'
---

<Counter client:visible />

client:visible loads and hydrates the component when it enters the viewport.

Astro calls these interactive components client islands. The rest of the page remains plain HTML. The official islands architecture guide goes deeper into this model.

Curious how much JavaScript each framework actually ships to the browser? Check my free Astro islands cost calculator.

Create your first Astro project

Run the current Astro setup wizard:

npm create astro@latest

Choose an empty starter while learning. The wizard can also install dependencies and initialize a Git repository for you.

Enter the project directory and start the development server:

cd my-astro-site
npm run dev

The terminal prints the local URL. Open that URL in your browser.

See the official Astro installation guide for the current Node.js requirements and other package managers.

The Astro project structure

An Astro project commonly looks like this:

public/
src/
  components/
  layouts/
  pages/
astro.config.mjs
package.json
tsconfig.json

src/pages is special. Astro uses its files to create routes.

For example:

src/pages/index.astro becomes /
src/pages/about.astro becomes /about
src/pages/blog/index.astro becomes /blog

src/components and src/layouts are useful conventions, but you can organize them differently.

Files inside public are copied without processing. Put assets there only when you want Astro to leave them untouched.

The official project structure guide documents each directory.

What does an Astro component look like?

An .astro file has an optional component script between two --- fences, followed by the template:

---
const name = 'Flavio'
---

<h1>Hello {name}</h1>

<style>
  h1 {
    color: navy;
  }
</style>

The component script runs when Astro renders the component. It does not get sent to the browser.

Astro scopes the component’s CSS by default. You can also use standard <script> tags when a small piece of browser JavaScript is enough.

Read the official Astro components guide for props, slots, scripts, and styles.

Build and deploy

Create a production build with:

npm run build

With the default static output, Astro writes the site to dist/. You can publish that directory on a static host.

If your site uses on-demand rendering, install the adapter for your runtime before deploying. Astro maintains adapters for platforms including Cloudflare, Netlify, Node.js, and Vercel.

The official deployment guide has current instructions for each platform.

Here are the posts in the Astro series:

Tagged: Astro · All topics

~~~