How to Build a Website with Astro: The Ultimate Guide

Astro is the web framework for building content-driven websites like blogs, marketing sites, and e-commerce stores. It’s designed for speed, shipping zero JavaScript by default. In this guide, we’ll walk you through everything you need to know to build your first Astro site from scratch.

1. Prerequisites

Before we dive in, make sure you have Node.js installed on your system. Astro requires Node.js version 18.17.1, 20.3.0, or higher.

To check your version, open your terminal and run:

node -v

2. Choosing Your IDE (Integrated Development Environment)

A great developer experience starts with the right tools. Here are the top choices for Astro development:

Visual Studio Code (Recommended)

VS Code is the most popular editor for Astro. To get the best experience, you must install the Astro VS Code Extension. It provides syntax highlighting, intellisense, and error checking for .astro files.

Cursor

Curor is an AI-powered code editor that is fully compatible with VS Code extensions. Since it’s built on top of VS Code, the Astro extension works perfectly here too.

WebStorm / JetBrains IDEs

If you prefer JetBrains products, you can install the “Astro” plugin from the JetBrains Marketplace to get support for .astro files.

3. Starting Your Project

Astro provides a handy CLI tool to scaffold your project. Open your terminal and navigate to the directory where you want to create your project.

MacOS / Linux Terminal

cd ~/Documents/Projects

npm create astro@latest

Windows (Command Prompt or PowerShell)

cd C:\Users\YourName\Documents\Projects

npm create astro@latest

The wizard will ask you a few questions:

Where should we create your new project? (e.g., ./my-astro-site)
How would you like to start your new project? (We recommend “Include sample files”)
Install dependencies? (Yes)
Initialize a new git repository? (Yes)
How would you like to setup TypeScript? (Strict)

4. The Project Structure

Once the installation is complete, open the folder in your IDE. You’ll see several directories:

src/: Where your source code lives.
- components/: Reusable UI components.
- layouts/: Templates for your pages.
- pages/: Files here automatically become routes (e.g., index.astro is /).
public/: Static assets like images and fonts.
astro.config.mjs: Your Astro configuration file.

5. Building Your First Page

Astro components use a file extension called .astro. They are composed of two main parts: the Component Script (frontmatter) and the Component Template (HTML).

Edit src/pages/index.astro:

---
// Component Script (JavaScript/TypeScript)
const pageTitle = "My Awesome Astro Site";
const items = ["Fast", "Modern", "Easy"];
---

<html lang="en">
  <head>
    <title>{pageTitle}</title>
  </head>
  <body>
    <h1>Welcome to {pageTitle}</h1>
    <ul>
      {items.map((item) => <li>{item}</li>)}
    </ul>
    
    <style>
      h1 { color: #ff5d01; }
    </style>
  </body>
</html>

6. The “Magic” of Multi-Framework Support

One of Astro’s best features is that you can use components from React, Vue, Svelte, or Solid all in one project.

To add React, run:

npx astro add react

Then you can use a React component in your Astro page:

---
import MyReactButton from '../components/MyReactButton.jsx';
---

<MyReactButton client:load />

Understanding Client Directives

Astro ships zero JavaScript by default. If you want a component to be interactive on the client side, you must use a “client directive”:

client:load: Hydrate the component immediately on page load.
client:idle: Hydrate once the main thread is free.
client:visible: Hydrate only when the component enters the viewport.

7. Running Your Site Locally

To see your changes in real-time, start the development server.

MacOS / Linux

npm run dev

Windows

npm run dev

Your site will usually be available at http://localhost:4321.

8. Deploying Your Site

Astro is incredibly easy to deploy. You can use any static hosting provider.

Cloudflare Pages: High speed, integrated with Wrangler.
Vercel: Seamless integration with GitHub.
Netlify: Great for quick previews and forms.

To build your site for production, run:

npm run build

Conclusion

Building with Astro allows you to create lightning-fast websites with the tools you already know and love. Whether you’re a seasoned pro or just starting out, Astro’s developer experience and performance-first approach make it a top-tier choice for 2026.

Happy coding!