A Look at Building with Astro

Avatar of Chris Coyier
Chris Coyier on (Updated on )

DigitalOcean provides cloud products for every stage of your journey. Get started with $200 in free credit!

Astro is a brand new framework for building websites. To me, the big thing is that it allows you to build a site like you’re using a JavaScript framework (and you are), but the output is a zero-JavaScript static site. You can opt-in to client-side JavaScript as needed, and there are clever options for doing so. Notably, the learning curve is somewhat flattened by the fact that it supports componentry you may already know: React/Preact (JSX), Svelte, Vue, or web components.

Table stakes

Starting a new project is as easy as it should be:

npm init astro
npm install
npm start

There is a helpful little process and output:

As expected (like you would get with Next or Nuxt or any other site builder kind of project) you get a dev server at a local port you can pop right up:

From here, I consider the table stakes to be CSS injection / Hot Module Reloading. No worries there:

A static site generator with honest-to-god real actual components

This is such a wonderful thing to me. I really like the idea of static site generators—I think they make a lot of sense in a lot of situations. Sending HTML over-the-wire is just a good move for resiliency, CDN-efficiency, SEO, accessibility, you name it. But in the past a lot of the options were either:

  • A JavaScript powered static site generator, that does generate a “static” site, but also ships a JavaScript bundle (e.g. Next or Gatsby)
  • A static site generator that is more focused on HTML and has its own templating/formats that aren’t JavaScript components (e.g. Eleventy or Jekyll)

I know there are exceptions, but this covers the vast majority of the site generator market.

But I want both!

  • I want to craft sites from JavaScript-components, because the syntax and tooling around them is just better than any other component system we have right now.
  • I want static output that is actually zero-JavaScript (unless I manually opt-in to things).

That’s what happens with Astro.

Those components?

  • They can be .jsx files
  • They can be .svelte files
  • They can be .vue files
  • These are “renderers” and you can BYO.

Astro also has it’s own format (.astro) and it’s also very compelling because:

  • It’s obviously a first-class citizen of how Astro works
  • It’s comfortably JSX-like…
  • …except better because it does stuff like makes the <head> work automatically
  • Styled scoping works out of the box, through a normal <style> tag
  • “Fenced” JavaScript runs during build. Let’s look at that next.

Astro files

I mentioned some of the cool parts about the .astro syntax right above. At a higher level, I just like how they look. So little boilerplate! Just gets right to it.

import SomeComponent from "../components/SomeComponent";

// This runs in Node, so you look at your command line to see it.

// Example: <SomeComponent greeting="(Optional) Hello" name="Required Name" />
const { greeting = 'Hello', name } = Astro.props;
const items = ["Dog", "Cat", "Platipus"];
<!-- JSX-like, but also more pleasantly HTML like, like this comment  -->
<div class="module">
  <h1>{greeting}, {name}!</h1>
    {items.map((item) => (

<SomeComponent regular="props" />

   /* Scoped! */
  .module {
    padding: 1rem;

The “fences” (---) at the top is where the initial JavaScriptin’ goes. That’s where I yank in the props for this component if it needs any (they can be typed if you like that), do imports/exports, and set up data for the template below.

What feels a little funky, but is in-line with the Astro vibe, is that this is essentially Node JavaScript. It runs in the build process. So that console.log() statement I don’t see in my browser console, I see it in my command line.

pages-style routing

It’s tempting to say Next.js popularized this, but really the concept is as old as file systems. Think of how a classic Apache server works. If you have a file system like:


In a browser, you can visit http://website.com/about and that will render that index.html page under the /about folder. That’s what the routing is like here. By virtue of me having:


I’ll have a homepage as well as an /about/ page on my site. That’s just a refreshingly nice way to deal with routing—as opposed to needing to build your own routing with component-ry all to itself.

If you want to do that thing where all the content of your site lives in Markdown files right in the repo, that’s a first-class citizen.

I think this is super common for stuff like blogs and documentation, especially as those are already popular targets for static site generators. And in these early days, I think we’re going to see a lot of Astro sites along those lines while people wait to see if it’s ready for bigger undertakings.

One way to use Markdown is to make Pages in Markdown straight away. The Markdown will also have “fences” (Frontmatter) where you chuck what layout you want to use (best to use an .astro file) and pass in data if you need to. Then the entire content of the Markdown file will flow into the <slot />. Pretty darn slick:

Another incredibly satisfying way to use Markdown in Astro is using the built-in <Markdown /> component. Import it and use it:

import { Markdown } from 'astro/components';

    # Hello world!
    - Do thing
    - Another thing in my *cool list*

  <div>Outside Markdown</div>

You can also go snag some Markdown from elsewhere in your project and barf that into a component. That leads into fetching data, so let’s look at that next.

Fetching data rules

We were just talking about Markdown so let’s close the loop there. You can “fetch” data internally in Astro by using fetchContent. Look how straightforward it is:

I fetch it the raw Markdown, then I could use the HTML it returns if I want, or slap it into a <Markdown /> component if that makes sense for whatever reason:

import { Markdown } from 'astro/components';
const localData = Astro.fetchContent('../content/data.md');

<div class="module">
  <Markdown content={localData[0].astro.source} />

But I don’t have to fetch internal data only. I’m a fan of Eleventy. During an Eleventy build, you can certainly go fetch data from an outside source, but I’d argue it’s a little finnicky. You fetch the data with code in a separate JavaScript file, pulling in your own network library, then processing and returning the data to use elsewhere in a template. Like this. In Astro, that fetching can happen right alongside the component where you need it.

Check out this real-world-ish example where I yank in data from right here from CSS-Tricks and display it as cards.

import Card from '../components/Card.astro';
import Header from '../components/Header';

const remoteData = await fetch('https://css-tricks.com/wp-json/wp/v2/posts?per_page=12&_embed').then(response => response.json());

<!doctype html>
<html lang="en">

    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <link rel="icon" href="data:image/svg+xml,<svg xmlns=%22http://www.w3.org/2000/svg%22 viewBox=%220 0 100 100%22><text y=%22.9em%22 font-size=%2290%22>⭐️</text></svg>">
    <link rel="stylesheet" href="/style/global.css">

    <style lang="scss">
      .grid {
        margin: 4rem;
        display: grid;
        grid-template-columns: repeat(2, 1fr);
        @media (max-width: 650px) {
          grid-template-columns: repeat(1, 1fr);
          margin: 2rem;
        gap: 3rem;

    <Header />

    <div class="grid">
      {remoteData.map((post) => {



I can build a page from CSS-Tricks data just that easily:

What’s fascinating about that is that the data happens:

  1. in Node, not client-side, and
  2. during the build process.

So, in order to keep a website like this updated, I’d have to run the build/deploy process regularly.

I suppose it’s kind of weird how Astro supports all these different frameworks out of the box.

I’ve overheard some pushback that Astro is inefficient at the npm install level since you have to bring down a bunch of stuff you likely won’t need or use. I’ve overheard some pushback on the idea that mixing-matching JavaScript frameworks is a terrible idea.

I agree it’s weird-feeling, but I’m not particularly worried about non-user-facing things. When things are happening only during the build process and all the user ever gets is HTML, use whatever feels good! If you ultimately do load the components-based frameworks to do on-page interactive things, surely it makes sense to limit it to one. And since you’re getting so much at build time, maybe it makes sense to use something designed for super light on-rendered-page interactivity.


Let’s say you want to use Sass to style your site. With many site generators, they punt on this, as a philosophy. Like saying “nah, we don’t want to be opinionated here, you style however you want to”. And I get that, it might be a strength as sometimes frameworks that are too opinionated lose people. But to me, it often feels unfortunate as now I’m on my own to wire up some style-processing build processes (e.g. Gulp) that I really just don’t want to deal with.

With Astro, the philosophy seems to be to support a wide swath of popular styling techniques out of the box right away.

  • Just import "./style.css"; vanilla stylesheets
  • Use a <style> block anywhere in .astro files and the CSS will be scoped to that component…
  • … which is like CSS modules, but that’s only needed if you go for a .jsx file, and if you do, it’s supported.
  • The styling capabilities of .svelte and .vue files work as expected.
  • Sass is built in, just put <style lang="scss"> on the styling blocks wherever.

The styling doc has more detail.

The fancy opt-in JavaScript tricks

Allow me to blockquote this from the README:

  • <MyComponent /> will render an HTML-only version of MyComponent (default)
  • <MyComponent:load /> will render MyComponent on page load
  • <MyComponent:idle /> will use requestIdleCallback() to render MyComponent as soon as main thread is free
  • <MyComponent:visible /> will use an IntersectionObserver to render MyComponent when the element enters the viewport

That’s some fancy dancing. HTML by default, and you opt-in to running your components client-side (JavaScript) only when you specifically want to, and even then, under efficient conditions.

I put a little Vue-based counter (from their examples) onto my demo site and used the :visible modifier to see it work. Check it out:

The Vue stuff only loads when it needs to. Like the blog post says:

Of course, sometimes client-side JavaScript is inevitable. Image carousels, shopping carts, and auto-complete search bars are just a few examples of things that require some JavaScript to run in the browser. This is where Astro really shines: When a component needs some JavaScript, Astro only loads that one component (and any dependencies). The rest of your site continues to exist as static, lightweight HTML.

The Discord is poppin’

I should point out that Astro is super duper new. As I write, they don’t even have real documentation up. It might feel a bit early to be using a framework with docs that only exist as a README. They are working on it though! I’ve seen previews of it because I happen to be in the Discord.

I think they are very smart to have a public Discord as it means there is a hot-n-fast feedback loop for them to improve the framework. I’ve found that being in it is super useful.

I believe they are hoping that Astro grows up into much more than a framework, but a complete platform, where Astro is just the open-source core. You can hear Fred talk with Jason about that on a Learn with Jason episode.