Quick Start
An Astro project is a Node package with a specific and deliberately small layout. Most of the files are yours to organise; the framework only requires that pages live under src/pages, that the configuration file sits at the project root, and that a build command produces a dist/ folder of static files. Because the layout is small, a project is quick to read end to end, and the number of concepts you have to hold in your head to make a change is correspondingly small.
The official scaffolder is the fastest way to start:
npm create astro@latest
The command asks for a project name, offers a set of starter templates, and asks whether to install dependencies and initialise a repository. The same command can be made non-interactive, which is what you want in a script or a container:
npm create astro@latest my-site -- --template minimal --no-install --no-git --yes
A minimal project looks like this:
my-site/
├── astro.config.mjs # project configuration and integrations
├── package.json
├── tsconfig.json
├── public/ # copied verbatim to the site root
│ └── favicon.svg
└── src/
├── assets/ # images and fonts processed by the build
├── components/ # reusable .astro and framework components
├── content/ # Markdown and MDX sources
├── layouts/ # page shells shared by several routes
├── pages/ # every route in the site
│ └── index.astro
└── styles/ # global stylesheets
The public directory is for files that should be served exactly as they are; anything in src/assets is processed by the build, which is what makes the image pipeline work. The src/pages directory is the one that is special, because every file inside it becomes a route.
A layout is the usual way to avoid repeating the document shell. It is an ordinary component that accepts props and renders a slot:
---
// src/layouts/BaseLayout.astro
import '../styles/global.css';
interface Props {
title: string;
description?: string;
}
const { title, description = 'Acme documentation' } = Astro.props;
---
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<meta name="description" content={description} />
<link rel="icon" type="image/svg+xml" href="/favicon.svg" />
<title>{title}</title>
</head>
<body>
<slot />
</body>
</html>
A page then uses the layout and puts its own content in the slot:
---
// src/pages/index.astro
import BaseLayout from '../layouts/BaseLayout.astro';
---
<BaseLayout title="Acme Docs" description="Everything you need to build with Acme.">
<main>
<h1>Acme Docs</h1>
<p>Start with the quickstart, or jump straight to the API reference.</p>
</main>
</BaseLayout>
Routing is derived from the file path, and the rules are short enough to memorise in a minute. src/pages/about.astro becomes /about, src/pages/docs/index.astro becomes /docs, and src/pages/blog/post.md becomes /blog/post. A file name in square brackets marks a dynamic segment, and it needs a getStaticPaths function that enumerates the paths to generate:
---
// src/pages/blog/[slug].astro
import BaseLayout from '../../layouts/BaseLayout.astro';
export async function getStaticPaths() {
const posts = [
{ slug: 'first-release', title: 'Our first release' },
{ slug: 'migrating', title: 'Migrating to v2' },
];
return posts.map((post) => ({
params: { slug: post.slug },
props: { post },
}));
}
const { post } = Astro.props;
---
<BaseLayout title={post.title}>
<h1>{post.title}</h1>
</BaseLayout>
A spread such as [...slug].astro captures the rest of the path, which is how catch-all routes are written. A route that ends with .md or .mdx is a content page rather than a template, and Astro renders it with the layout you point at in its frontmatter.
Where the files end up matters more in Astro than in most frameworks, because the build output is the deliverable. A successful npm run build produces a dist/ directory containing one HTML file per route, a directory of hashed assets for the JavaScript and CSS that were actually needed, and a copy of everything in public/. Nothing else is required at runtime, so that folder can be served by a static host, pushed to object storage behind a CDN, or opened from a local file server. There is no server process to keep alive, and no environment variables to inject, which is what makes a documentation site cheap to host and easy to reproduce. The preview command exists to reproduce that arrangement locally, so a habit worth forming early is to build and preview before every release rather than trusting the dev server alone.
The four commands you will use daily are short:
| Command | What it does |
|---|---|
npm run dev | Start the development server with hot reload |
npm run build | Build the production site into dist/ |
npm run preview | Serve the built dist/ folder locally |
npx astro check | Type-check templates and TypeScript, after installing @astrojs/check |
The check command is worth wiring into your editor or your CI, because it catches the mistakes that a plain build does not: a component imported with the wrong name, a prop that does not exist on the component you are using, a type mismatch in a frontmatter value.
Integrations are added with the same CLI that created the project, and the command edits the configuration file for you:
npx astro add react
npx astro add mdx sitemap
npx astro add tailwind
Two problems are common in the first hour. If the dev server refuses to start because a port is taken, pass a different one with npm run dev -- --port 4322. And if a component that reads window or document fails to render, the cause is that it is being rendered on the server; give it client:only="react" instead of client:load, which tells Astro to skip the server render and mount it only in the browser.
Once the dev server shows your page and the build produces a dist/ folder, the project is working. The next step is to replace the sample content with your own: define a content collection so your Markdown files are validated, add a layout that renders them, and point site in the configuration file at the real address, because that value feeds the canonical URLs and the sitemap.
