Installation & Setup

Prerequisites

Before you start you need:

Tool	Minimum version	Check with
Node.js	20.x	node --version
npm	10.x	npm --version
A code editor	—	VS Code recommended

Tip: Use nvm to manage Node.js versions. Run nvm use 20 to switch to Node 20 instantly.

Create a new project

The fastest way to start is the Astro CLI wizard:

npm create astro@latest my-site
cd my-site

The wizard asks a few questions:

1. How would you like to start your project? — choose Empty to start from scratch, or a template like Blog to get a head start
2. Install dependencies? — Yes
3. Initialize a git repository? — Yes

Start the dev server

npm run dev

Open http://localhost:4321 in your browser. You should see the Astro welcome page.

The dev server supports Hot Module Replacement — save any .astro file and the browser updates instantly without a full refresh.

Project structure

A fresh Astro project looks like this:

my-site/
├── public/          # Static files (favicon, images) — served as-is
├── src/
│   ├── components/  # Reusable .astro components
│   ├── layouts/     # Page shell layouts
│   ├── pages/       # Every file here becomes a URL route
│   └── styles/      # CSS files
├── astro.config.mjs # Astro configuration
├── package.json
└── tsconfig.json

The only special rule is src/pages/ — every .astro, .md, .mdx, or .ts file inside becomes a page or API endpoint.

Add Tailwind CSS

This site uses Tailwind CSS v4. Add it to any Astro project:

npm install tailwindcss @tailwindcss/postcss

Create postcss.config.mjs:

export default {
  plugins: { '@tailwindcss/postcss': {} },
}

Create src/styles/global.css:

@import "tailwindcss";

@theme {
  --color-brand: #FF5D01;
}

Import it in your base layout:

---
// src/layouts/BaseLayout.astro
import '../styles/global.css'
---

Note: In Astro 6, do not use @tailwindcss/vite — it conflicts with Astro’s Vite 8 / Rolldown build system. Always use @tailwindcss/postcss instead.

Add TypeScript

TypeScript is enabled by default in Astro. The generated tsconfig.json uses "extends": "astro/tsconfigs/strict" which is the recommended setting.

Add a path alias so you can import with @/ instead of ../../:

// tsconfig.json
{
  "extends": "astro/tsconfigs/strict",
  "compilerOptions": {
    "baseUrl": ".",
    "paths": { "@/*": ["src/*"] }
  }
}

Build for production

npm run build

Output goes to dist/. For a static site this is ready to upload to any host. For SSR, see the Self-Hosting guide →.

Useful scripts

Command	What it does
npm run dev	Start dev server at localhost:4321
npm run build	Build for production → dist/
npm run preview	Preview the production build locally
npx astro check	TypeScript type-check your .astro files
npx astro add <name>	Install and configure an official integration