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 -v2. 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
Cursor 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@latestWindows (Command Prompt or PowerShell)
cd C:\Users\YourName\Documents\Projects
npm create astro@latestThe 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.astrois/).
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 reactThen 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 devWindows
npm run devYour 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.
- Edge worker platforms: High speed, zero cold starts on V8-isolate runtimes, integrated CLI tooling.
- Vercel: Seamless integration with GitHub.
- Netlify: Great for quick previews and forms.
To build your site for production, run:
npm run build9. Astro Best Practices
Getting a site running is the easy part. These are the Astro best practices that keep it fast and maintainable once it grows, learned from shipping production Astro sites for clients:
- Ship zero JavaScript by default. Astro’s biggest advantage is that plain
.astrocomponents render to pure HTML. Reach for a framework island only when something is genuinely interactive. - Pick the laziest
client:directive that works.client:visiblefor anything below the fold,client:idlefor low-priority widgets, andclient:loadonly for above-the-fold interactivity. Every island you defer is JavaScript your visitor never waits for. - Use content collections for structured content. Defining a schema with Zod turns typos in frontmatter into build errors instead of silent production bugs.
- Let Astro optimize your images. The built-in image tooling converts to modern formats like AVIF and WebP, sets width and height to prevent layout shift, and lazy-loads by default.
- Prerender everything you can. Static HTML on a CDN edge beats a server render every time. Reserve SSR for pages that truly depend on the request.
- Keep scripts idempotent. If you use the ClientRouter for view transitions, scripts run once but pages swap many times. Re-run your init on
astro:page-loadand guard listeners so they bind once. - Scope your styles. Astro scopes component
<style>blocks automatically. Share design tokens through CSS custom properties instead of global class soup. - Run
astro checkin CI. Type errors in templates surface before deploy, not after. - Set a performance budget. Measure with Lighthouse before and after each feature. It is much easier to keep a fast site fast than to rescue a slow one.
- Update on a schedule. Astro moves quickly. Small, regular version bumps are painless; a two-major-version jump rarely is.
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!
