Setup

Get an Astro project running from scratch.

Requirements

• Node.js v22.12.0 or higher (even-numbered versions only)
• A text editor (VS Code recommended with Astro extension)

Create a project

npm create astro@latest

The CLI wizard walks you through:

1. Project directory name
2. Starter template (empty, blog, docs/Starlight, etc.)
3. Install dependencies
4. Initialize git
5. TypeScript strictness

For a blank start:

npm create astro@latest -- --template minimal

For a blog:

npm create astro@latest -- --template blog

Project structure

my-site/
  astro.config.mjs    # Astro configuration
  tsconfig.json        # TypeScript config
  package.json
  src/
    pages/             # File-based routes (required)
    components/        # Reusable components
    layouts/           # Page layouts
    styles/            # CSS files
    content/           # Content collections
  public/              # Static assets (copied as-is to output)

Dev server

npm run dev

Runs at http://localhost:4321/ with hot module replacement via Vite.

Build and preview

npm run build      # Build to dist/
npm run preview    # Preview the built site locally

Configuration

astro.config.mjs is where you configure everything:

import { defineConfig } from 'astro/config';
import react from '@astrojs/react';
import tailwind from '@astrojs/tailwind';

export default defineConfig({
  site: 'https://example.com',
  integrations: [react(), tailwind()],
  output: 'static',
});

Add integrations

Use astro add for one-command integration setup:

npx astro add react          # React support
npx astro add tailwind       # Tailwind CSS
npx astro add mdx            # MDX support
npx astro add sitemap        # Sitemap generation
npx astro add node           # Node.js SSR adapter

You can chain them:

npx astro add react tailwind mdx

TypeScript

Astro has built-in TypeScript support. The tsconfig.json extends Astro’s base config:

{
  "extends": "astro/tsconfigs/strict"
}

Options: base, strict, strictest.

Type-check your project:

npx astro check

Editor setup

Install the Astro VS Code extension for:

• Syntax highlighting for .astro files
• TypeScript IntelliSense
• Formatting
• Diagnostics

Import aliases

Configure path aliases in tsconfig.json:

{
  "extends": "astro/tsconfigs/strict",
  "compilerOptions": {
    "paths": {
      "@components/*": ["./src/components/*"],
      "@layouts/*": ["./src/layouts/*"],
      "@assets/*": ["./src/assets/*"]
    }
  }
}