Skip to content

Astro Project Structure — Complete Guide

DodaTech Updated 2026-06-28 3 min read

In this tutorial, you will learn about Astro Project Structure. We cover key concepts, practical examples, and best practices to help you master this topic.

Learn the Astro project structure including src/, public/, config files, and how each directory contributes to your site's routing and asset management.

In this lesson, you'll explore every directory and file in an Astro project, understand their purposes, and learn how to organize your code for maintainability. Astro follows a convention-over-configuration approach that keeps projects predictable.

What You'll Learn

The function of src/pages/, src/components/, src/content/, public/, and configuration files, plus best practices for organizing larger projects.

Why It Matters

Understanding the project structure prevents misplaced files that break routing, asset loading, or build output. It also makes collaboration easier when every developer knows where to find specific code.

Real-World Use

DodaTech's tutorial site organizes hundreds of lessons using Astro's content collections and component directories, keeping documentation maintainable at scale.

flowchart TD
    A["astro.config.mjs"] --> B[src/]
    B --> C[pages/]
    B --> D[components/]
    B --> E[content/]
    B --> F[layouts/]
    A --> G[public/]
    H[package.json] --> A
    style B fill:#ff5a03,color:#fff

Core Directories

src/pages/

Every file here becomes a route. The file path determines the URL:

src/pages/index.astro       → /
src/pages/about.astro       → /about
src/pages/blog/post-1.astro → /blog/post-1

src/components/

Reusable pieces of UI. Files here do NOT become routes. Import them into pages:

---
import Header from "../components/Header.astro";
import Footer from "../components/Footer.astro";
---
<Header />
<main>Page content</main>
<Footer />

src/content/

Contains content collections for type-safe Markdown and MDX management. Each subdirectory is a collection:

src/content/
  blog/
    post-1.md
    post-2.md
  docs/
    getting-started.md

src/layouts/

Layout wrappers that provide a consistent page structure:

---
// src/layouts/BaseLayout.astro
export interface Props {
  title: string;
}
const { title } = Astro.props;
---
<!DOCTYPE html>
<html>
  <head><title>{title}</title></head>
  <body><slot /></body>
</html>

public/

Static assets served as-is: images, fonts, robots.txt, favicon. Files here are copied to the build output without processing. Reference them by root-relative path: /images/logo.png.

Configuration Files

astro.config.mjs controls integrations, SSR adapters, site URL, and build behavior:

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

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

Common Mistakes

  1. Putting pages in src/components/: Files in components/ don't become routes. Only src/pages/ generates URLs.
  2. Using public/ for processed assets: Astro doesn't hash or optimize files in public/. Use src/ and import assets for processing.
  3. Missing site in config: RSS, sitemap, and canonical URLs require site in astro.config.mjs.
  4. Nesting pages too deep: Deeply nested directories create long URLs like /a/b/c/d. Keep routes shallow.
  5. Forgetting the src/content/config.ts for collections: Content collections need a schema file to validate frontmatter.

Practice Questions

  1. Which directory holds reusable UI pieces? Answer: src/components/. These must be imported into pages or layouts.

  2. Where do static files like robots.txt go? Answer: public/. They are copied directly to the build output.

  3. How do content collections differ from pages? Answer: Content collections are type-managed Markdown/MDX files in src/content/, while pages in src/pages/ define routes.

  4. What does the slot element do in a layout? Answer: It renders the child page content inside the layout component.

Challenge

Add a src/pages/team.astro page, create a src/layouts/TeamLayout.astro layout, apply it to the team page, and verify the route at /team.

Mini Project

Create a project with three directories in src/pages/: services/, pricing/, and contact/. Add an index file to each. Confirm all routes work.

FAQ

Can I use `src/assets/`?

: Yes. Astro processes assets imported from src/. Create any subdirectory you need.

What is the `dist/` directory?

: It's the build output. Astro generates it when you run npm run build. Deploy this folder.

Do I need a `src/layouts/` directory?

: No. Layouts are optional. Create one only when pages share a common shell.

How do I add custom directories?

: Create them. Astro only has special behavior for src/pages/, src/content/, public/, and src/components/.

Can I rename `src/`?

: No. The src/ directory name is fixed in Astro's convention.

What's Next

Move to Astro Pages to learn how to create pages with frontmatter, components, and dynamic content.

← Previous Astro Installation and Setup — Complete Beginner's Guide Next → Astro Pages — Creating Routes and Content

Built by the developers of DodaTech

Doda Browser, DodaZIP & Durga Antivirus Pro

Home Browse Astro