Astro Installation and Setup — Complete Beginner's Guide

Learn how to install Astro, set up a new project, configure the dev server, and understand the initial file structure step by step for building fast content-driven websites.

In this lesson, you'll install Astro, scaffold a new project, start the development server, and explore the initial file structure. Astro is a modern web framework that ships zero JavaScript by default and uses island architecture for interactivity.

What You'll Learn

How to create an Astro project from scratch, understand the directory layout, and run the dev server with hot reload.

Why It Matters

A proper setup ensures your build tooling works correctly, dependencies are resolved, and you can focus on building without configuration headaches later.

Real-World Use

Doda Browser uses Astro for its documentation site because fast setup and zero-JS output make developer docs load instantly on slow connections.

flowchart LR
    A[Install Node.js] --> B[Create Astro Project]
    B --> C[Explore File Structure]
    C --> D[Run Dev Server]
    D --> E[Build for Production]
    style D fill:#ff5a03,color:#fff

Step-by-Step Setup

1. Create a New Project

Open your terminal and run:

npm create astro@latest my-astro-site

The CLI prompts you to choose a starter template. Select "Basics" for the simplest setup. This creates a my-astro-site/ directory with the minimum files needed.

2. Install Dependencies

Navigate into the project and install dependencies:

cd my-astro-site
npm install

Astro downloads its core packages, including the compiler, dev server, and build tools.

3. Start the Dev Server

npm run dev

Output: The dev server starts at http://localhost:4321. Open it in your browser. You see a welcome page with links to Astro docs. Any change to a file triggers an instant hot reload.

4. Project Structure

The scaffolded project has this layout:

my-astro-site/
├── src/
│   ├── pages/       # Routes (.astro, .md, .mdx)
│   └── components/  # Reusable components
├── public/          # Static assets (images, fonts)
├── astro.config.mjs # Astro configuration
└── package.json     # Dependencies

The src/pages/ directory is the most important. Every .astro or .md file here becomes a route on your site.

5. Build for Production

npm run build

Output: Astro generates static HTML in the dist/ directory. Each page becomes a standalone HTML file with zero JavaScript by default.

Common Mistakes

1. Using Node.js 16 or older: Astro 4+ requires Node.js 18+. Check with node --version before starting.
2. Forgetting to install dependencies: Running npm run dev without npm install first fails with missing module errors.
3. Editing files outside src/: Astro only watches src/ for hot reload. Files in public/ require a manual refresh.
4. Ignoring the astro.config.mjs file: Configuration like integrations, SSR adapters, and site URL must be set here.
5. Running the wrong package manager: If you scaffold with npm, stick with npm. Mixing pnpm and npm node_modules causes conflicts.

Practice Questions

1. What is the minimum Node.js version for Astro 4+? Answer: Node.js 18 or higher.

2. Which directory holds your page routes? Answer: src/pages/. Every .astro and .md file here becomes a URL route.

3. What command starts the development server? Answer: npm run dev. It starts a hot-reloading server at http://localhost:4321.

4. Where does Astro output production builds? Answer: The dist/ directory, containing static HTML, CSS, and JS files.

Challenge

Scaffold an Astro project using the "Blog" template instead of "Basics", explore the additional files it creates, and compare the structure to the Basics template.

Mini Project

Create a new Astro project, add a file src/pages/about.astro with basic HTML content, verify it appears at http://localhost:4321/about, and run npm run build to confirm the output includes dist/about/index.html.

FAQ

What's Next

Continue to Astro Project Structure to understand the role of each folder and file in detail.