Project Structure

A fresh Astro project looks like this:

my-site/
├── public/
│   └── favicon.svg
├── src/
│   ├── components/
│   ├── layouts/
│   ├── pages/
│   │   └── index.astro
│   └── content.config.ts        # later
├── astro.config.mjs
├── package.json
└── tsconfig.json

src/pages/ — Routes

The most important folder. Every .astro, .md, .mdx, or .html file here becomes a page. src/pages/about.astro → /about.

You’ll see this in detail in the next chapter.

src/components/ — Reusable Components

Convention, not enforced. Any .astro file here is yours to import.

---
import Header from "../components/Header.astro";
---
<Header />

src/layouts/ — Page Wrappers

Also convention — layout components live here. A layout is just a component that wraps page content via <slot />.

public/ — Untouched Static Assets

Anything in public/ is served as-is from the site root. public/favicon.svg ships at https://yoursite.com/favicon.svg.

astro.config.mjs — Project Config

Where you register integrations and tweak settings:

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

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

You won’t touch this often — npm run astro add ... edits it for you when you add integrations.

tsconfig.json

Astro generates a TypeScript config that works out of the box, with strict mode and path aliases. You can extend the paths for project-specific aliases:

{
  "compilerOptions": {
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

Now import Header from "@/components/Header.astro" works everywhere.

Adding More Folders

Astro doesn’t care — add src/utils/, src/styles/, src/lib/ freely. Only src/pages/ and public/ have special meaning.

Up Next

The format Astro is built around — the .astro file.