Creating an Astro project

This chapter follows What is Astro.

These steps create a new project, explain the files the wizard generates, and show the commands you run day to day. You need a current Node.js LTS release.

Scaffold the project

Run the wizard and answer its prompts for a directory name, a starter template, dependency installation, and Git initialization:

1
npm create astro@latest

Pass a template to skip the template prompt. The minimal template is the cleanest starting point for learning; blog adds a content collection, RSS, and a sitemap.

1
npm create astro@latest -- --template minimal

pnpm and Yarn work the same way with pnpm create astro@latest and yarn create astro.

Know the project layout

1
my-site/
2
├── public/
3
│   └── favicon.svg
4
├── src/
5
│   ├── components/
6
│   ├── layouts/
7
│   ├── pages/
8
│   │   └── index.astro
9
│   └── styles/
10
├── astro.config.mjs
11
├── package.json
12
└── tsconfig.json

Only some of these names are special to Astro:

Path	Role
`src/pages/`	Required. Each file becomes a route (Routing in Astro).
`public/`	Copied to the build output unchanged: favicons, `robots.txt`, files that must keep their exact URL.
`src/content.config.ts`	Defines content collections, when you add them (Content collections in Astro).
`src/middleware.ts`	Runs before rendering requests, when you add it.
`src/actions/`	Type-safe server functions, when you add them.
`astro.config.mjs`	Project configuration and integrations.

components/, layouts/, and styles/ are conventions, not rules. Astro processes anything under src/ that a page imports, so you can organize the rest however you like.

Configure Astro

The generated config is nearly empty. Two settings are worth adding early: site, which Astro needs to build absolute URLs for sitemaps, RSS, and canonical links, and trailingSlash, which decides whether /about and /about/ are the same page.

1
import { defineConfig } from 'astro/config';
2

3
export default defineConfig({
4
  site: 'https://example.com',
5
  trailingSlash: 'always',
6
});

TypeScript works without extra setup. The wizard writes a tsconfig.json that extends one of Astro’s presets (base, strict, or strictest).

Run the development server

1
npm run dev

The dev server starts on http://localhost:4321 with hot module replacement. Edits to .astro files, Markdown, and styles appear without a full reload. The dev toolbar at the bottom of the page shows which components are islands and flags accessibility and performance problems; it never ships to production.

Add integrations

Integrations add UI frameworks, Markdown extensions, adapters, and build features. astro add installs the package and edits the config in one step:

1
npx astro add react
2
npx astro add mdx
3
npx astro add sitemap

Review the config diff it proposes before you accept. You can add several at once: npx astro add react mdx sitemap.

Build, preview, and check

1
npm run build
2
npm run preview
3
npx astro check

build writes the site to dist/. For a static site that folder is the whole deployment. preview serves dist/ locally so you can test the production output, including redirects and trailing-slash behavior that the dev server handles more loosely. astro check runs type checking and diagnostics across .astro files, which tsc alone does not understand; add it to CI next to your tests.

Next: Astro components.