Astro Project Structure
The default folders in an Astro project — pages, components, layouts, and public — and what lives where.
2 min read
Scaffolding a new Astro project (npm create astro@latest) produces a small, predictable folder layout. Knowing what each folder is for makes the rest of this course easier to follow, since almost every lesson refers back to one of these.
my-astro-site/
├── src/
│ ├── pages/
│ ├── components/
│ ├── layouts/
│ └── content/
├── public/
├── astro.config.mjs
└── package.jsonsrc/pages/ — your routes
Every file in src/pages/ becomes a page on your site, based on its file path. src/pages/about.astro becomes /about. This is file-based routing, and it's covered in its own lesson later — for now, just know that this folder is special: Astro scans it and wires up routing automatically, with no router configuration to write yourself.
src/components/ — reusable pieces
Anything you'd want to reuse across pages — a header, a card, a button — lives here as an .astro file (or a React/Vue/Svelte file, if you've added that integration). Unlike pages/, nothing in components/ is automatically routed; a component only renders where you explicitly import and use it.
---
// src/pages/index.astro
import SiteHeader from "../components/SiteHeader.astro";
---
<SiteHeader />
<main>Home page content</main>src/layouts/ — shared page shells
Layouts are just components too, but by convention they wrap a whole page: the <html>/<head>/<body> skeleton, shared navigation, a footer. Pages import a layout and pass their own content into it via a <slot />, so you're not repeating boilerplate markup on every page. The dedicated layouts lesson covers this pattern in full.
src/content/ — structured content
This folder holds content collections: Markdown or MDX files (blog posts, docs pages) validated against a schema you define in code. It's optional — plenty of small sites skip it — but it's the standard place to keep structured content once a site grows past a couple of hand-written pages.
public/ — files served as-is
Anything in public/ is copied to the output directory untouched, with no processing: favicons, robots.txt, PDFs, images you don't need Astro's image optimization for. If you reference public/logo.svg, the URL is /logo.svg — no import needed, because nothing about the file changes.
astro.config.mjs — project configuration
This is where you register integrations (React, Tailwind, sitemap, etc.), set the output mode (static vs. server — covered later), and configure build options. A fresh project's config file is nearly empty; it grows as you add capabilities.
The important thing to internalize early: pages/ is routing, everything else is organizational convention you can largely name and arrange the way you like, with components/, layouts/, and content/ being the common, well-supported defaults.