Project structure overview in Astro - Deep Dive

Overview - Project structure overview

What is it?

A project structure overview in Astro shows how files and folders are organized in an Astro project. It helps you understand where to put your pages, components, styles, and assets. This structure guides how Astro builds and serves your website. Knowing it makes working with Astro easier and faster.

Why it matters

Without a clear project structure, your code can become messy and hard to maintain. You might lose track of where things belong, slowing down development and causing bugs. A good structure helps teams work together smoothly and makes adding new features simpler. It also helps Astro know how to build your site correctly.

Where it fits

Before learning project structure, you should know basic web development concepts like HTML, CSS, and JavaScript. After understanding the structure, you can learn about routing, components, and data fetching in Astro. This knowledge fits early in your Astro learning path, right after setup and before advanced features.

Mental Model

Core Idea

Project structure is the organized map of your Astro files that tells the framework how to build and display your website.

Think of it like...

It's like organizing a kitchen: you have drawers for utensils, shelves for spices, and a fridge for perishables. When everything is in its place, cooking is smooth and fast.

astro-project/
├── public/          # Static files like images and fonts
├── src/
│   ├── components/  # Reusable UI pieces
│   ├── layouts/     # Page layouts
│   ├── pages/       # Website pages and routes
│   ├── styles/      # CSS or styling files
│   └── data/        # Data files or helpers
├── astro.config.mjs # Astro configuration
└── package.json     # Project metadata and dependencies

Build-Up - 7 Steps

1

Foundation

Understanding the src folder role

Concept: Learn what the src folder is and why it holds most of your code.

In Astro, the src folder is where you write your website's code. It contains pages, components, styles, and other resources. This keeps your code separate from static files and configuration. Think of src as your workspace where you build the site.

Result

You know where to put your code files so Astro can find and use them.

Understanding src as the main workspace helps you organize your code logically and find files quickly.

2

Foundation

Role of the public folder

Concept: Discover how the public folder stores static assets served as-is.

The public folder holds files like images, fonts, or icons that don’t change during build. Astro copies these files directly to the final website without processing. This is where you put things that need a fixed URL.

Result

You can add images or files that your site uses without worrying about build steps.

Knowing public is for static assets prevents confusion about where to place files that don’t need code processing.

3

Intermediate

Pages folder and routing connection

🤔Before reading on: do you think every file in pages becomes a website route or only some? Commit to your answer.

Concept: Learn how files in src/pages map to website URLs automatically.

Astro uses the pages folder to create routes. Each file here becomes a page on your site. For example, src/pages/about.astro becomes /about URL. Nested folders create nested routes. This automatic routing saves you from manual setup.

Result

You understand how to create new pages by adding files in the right place.

Knowing pages controls routing helps you build site navigation naturally and avoid routing mistakes.

4

Intermediate

Components folder for reusable UI

🤔Before reading on: do you think components can be used only once or multiple times? Commit to your answer.

Concept: Components are small pieces of UI you can reuse across pages and layouts.

The components folder holds UI parts like buttons, headers, or cards. You write them once and use them many times. This keeps your code DRY (Don’t Repeat Yourself) and easier to update. Components can accept data to change how they look or behave.

Result

You can build modular UI that is easier to maintain and update.

Understanding components as reusable building blocks improves code quality and speeds up development.

5

Intermediate

Layouts folder for page templates

Concept: Layouts define common structures shared by multiple pages, like headers and footers.

In layouts, you create templates that wrap pages with shared UI parts. For example, a main layout might include a navigation bar and footer. Pages then use this layout to keep a consistent look. This avoids copying the same code into every page.

Result

You can create consistent page designs easily and update them in one place.

Knowing layouts separate page content from shared structure helps keep your site design consistent and maintainable.

6

Advanced

Config and package files explained

🤔Before reading on: do you think astro.config.mjs changes how your site builds or just stores info? Commit to your answer.

Concept: Learn the role of configuration and metadata files in the project root.

The astro.config.mjs file tells Astro how to build your site, like setting base URLs or integrations. The package.json manages project dependencies and scripts. These files control how your project runs and builds but don’t affect page content directly.

Result

You understand where to customize build settings and manage dependencies.

Knowing config files control build behavior helps you customize and troubleshoot your project setup.

7

Expert

How Astro uses project structure internally

🤔Before reading on: do you think Astro scans all folders equally or only specific ones for building? Commit to your answer.

Concept: Astro scans specific folders like src/pages and src/components to build routes and UI, ignoring others.

During build, Astro looks into src/pages to create routes, src/components for reusable UI, and public for static assets. It ignores unrelated folders to optimize build speed. This scanning is smart and incremental, so only changed files trigger rebuilds. Understanding this helps optimize project layout and build performance.

Result

You grasp how Astro’s build process depends on project structure for efficiency.

Knowing Astro’s selective scanning prevents placing files in wrong folders that slow builds or cause errors.

Under the Hood

Astro’s build system reads the project folders to map files to website parts. It treats src/pages as routes, compiling each file into HTML or server-rendered pages. Components in src/components are compiled into reusable UI chunks. The public folder is copied directly to the output without changes. Configuration files guide how this process runs, including plugins and integrations. This modular scanning and compiling make builds fast and predictable.

Why designed this way?

Astro’s structure was designed to be simple and intuitive, reducing manual setup. By convention, it knows where to find pages and components, so developers focus on content, not config. This approach balances flexibility with ease of use. Alternatives like manual routing or complex config files were rejected to keep the developer experience smooth and beginner-friendly.

Project Root
├─ astro.config.mjs  <-- Build settings
├─ package.json      <-- Dependencies
├─ public/           <-- Static assets copied as-is
└─ src/
   ├─ pages/         <-- Files become website routes
   ├─ components/    <-- Reusable UI pieces
   ├─ layouts/       <-- Page templates
   ├─ styles/        <-- CSS files
   └─ data/          <-- Helpers and data

Build Process:
[astro.config.mjs] --> Configures build
[src/pages] --------> Generates routes
[src/components] ---> Compiled UI parts
[public] ----------- > Copied static files

Output: Final website files ready to deploy

Myth Busters - 4 Common Misconceptions

Quick: Do you think files in the public folder get processed by Astro during build? Commit yes or no.

Common Belief: Files in the public folder are processed and optimized by Astro during build.

Reality: Astro copies files in the public folder directly to the output without processing or optimization.

Why it matters: Expecting processing can lead to placing files in public that need transformations, causing broken images or missing optimizations.

Quick: Do you think you can put pages anywhere in src and Astro will route them? Commit yes or no.

Common Belief: Any file inside src will automatically become a route in the website.

Reality: Only files inside src/pages become routes. Files elsewhere are ignored for routing.

Why it matters: Placing pages outside src/pages causes them not to appear on the site, confusing beginners.

Quick: Do you think layouts are mandatory for every page? Commit yes or no.

Common Belief: Every page must use a layout to work correctly in Astro.

Reality: Layouts are optional helpers for shared structure; pages can work without them.

Why it matters: Thinking layouts are mandatory can complicate simple pages and confuse new learners.

Quick: Do you think astro.config.mjs is required for every Astro project? Commit yes or no.

Common Belief: Every Astro project must have an astro.config.mjs file to run.

Reality: Astro can run without a config file using defaults; config is only needed for customization.

Why it matters: Believing config is mandatory may intimidate beginners or cause unnecessary files.

Expert Zone

1

Astro’s build system uses file timestamps and content hashes to only rebuild changed pages, speeding up development.

2

You can customize the project structure by configuring the root or pages directory in astro.config.mjs, but this is rarely needed.

3

Components can be colocated with pages for better modularity, but this requires careful import paths to avoid confusion.

When NOT to use

Astro’s default project structure is great for most static and server-rendered sites. However, for very large apps with complex routing needs, frameworks like Next.js or Remix might be better. Also, if you need full control over routing or backend logic, Astro’s conventions might feel limiting.

Production Patterns

In production, teams often separate components into shared libraries for reuse across projects. They use layouts extensively for consistent branding. The public folder is carefully managed to avoid large unoptimized assets. Configuration files include integrations for CMS, image optimization, and deployment targets.

Connections

MVC Architecture

Project structure in Astro loosely maps to MVC parts: pages as views, components as reusable UI, and data/helpers as models.

Understanding MVC helps grasp why Astro separates pages, components, and data, improving code organization.

File System Organization

Astro’s project structure follows principles of clear file system organization used in software engineering.

Good file organization reduces cognitive load and errors, a principle true across all software projects.

Library Classification in a Library Science

Just like books are categorized into sections for easy finding, Astro organizes code into folders for easy access and maintenance.

Recognizing this connection shows how organizing information well is a universal challenge beyond programming.

Common Pitfalls

#1 Placing page files outside src/pages folder.

Wrong approach:

src/home.astro # expecting this to be a route

Correct approach:

src/pages/home.astro # correct location for routing

Root cause:

Misunderstanding that only files in src/pages become routes.

#2 Putting images inside src instead of public folder.

Wrong approach:

src/images/logo.png # expecting direct URL access

Correct approach:

public/images/logo.png # accessible as /images/logo.png

Root cause:

Confusing static assets with code files and their handling by Astro.

#3 Editing astro.config.mjs without understanding defaults.

Wrong approach:

astro.config.mjs with wrong base URL causing broken links

Correct approach:

astro.config.mjs with correct base URL matching deployment path

Root cause:

Not knowing the impact of config settings on site routing and asset loading.

Key Takeaways

Astro’s project structure organizes your code and assets into clear folders that guide how your site is built and served.

The src/pages folder controls your website’s routes, while src/components holds reusable UI pieces to keep code clean.

The public folder is for static files copied directly without processing, important for images and fonts.

Configuration files like astro.config.mjs customize build behavior but are optional for simple projects.

Understanding this structure helps you build, maintain, and scale Astro projects efficiently and avoid common mistakes.

Practice

1. In an Astro project, which folder is primarily used to store your source code like components and pages?

easy

A. src/

B. public/

C. assets/

D. dist/

Solution

1. Step 1: Understand folder roles in Astro

   The src/ folder is where you put your source code like components, pages, and styles.

2. Step 2: Identify the correct folder for code

   The public/ folder is for static files like images, not code.

3. Final Answer:

   src/ -> Option A

4. Quick Check:

   Source code folder = src/ [OK]

Hint: Code lives in src/, static files in public/ [OK]

Common Mistakes:

• Confusing public/ with src/
• Thinking assets/ is default code folder
• Assuming dist/ holds source code

2. Which of the following is the correct way to reference a static image stored in the public/ folder inside an Astro component?

easy

A. <img src="../src/images/photo.jpg" />

B. <img src="src/images/photo.jpg" />

C. <img src="/images/photo.jpg" />

D. <img src="./public/images/photo.jpg" />

Solution

1. Step 1: Understand how public/ files are served

   Files in public/ are served from the root URL, so you reference them with a leading slash.

2. Step 2: Choose the correct path format

   Using /images/photo.jpg correctly points to public/images/photo.jpg.

3. Final Answer:

   <img src="/images/photo.jpg" /> -> Option C

4. Quick Check:

   Static files use root-relative paths [OK]

Hint: Static files use root-relative paths starting with '/' [OK]

Common Mistakes:

• Using relative paths like 'src/images' for public files
• Including 'public/' in the path
• Using relative paths that don't work in deployed site

3. Given this Astro project structure:

project/
├─ public/
│  └─ logo.png
├─ src/
│  └─ components/
│     └─ Header.astro
└─ src/pages/index.astro

What will be the correct way to display logo.png inside Header.astro?

medium

A. <img src="src/public/logo.png" alt="Logo" />

B. <img src="../public/logo.png" alt="Logo" />

C. <img src="./logo.png" alt="Logo" />

D. <img src="/logo.png" alt="Logo" />

Solution

1. Step 1: Recall how public/ files are served

   Files in public/ are served from the root URL, so you use a root-relative path starting with '/'.

2. Step 2: Apply correct path in component

   Using /logo.png correctly points to the image regardless of component location.

3. Final Answer:

   <img src="/logo.png" alt="Logo" /> -> Option D

4. Quick Check:

   Public files use root-relative paths [OK]

Hint: Always use root-relative paths for public folder files [OK]

Common Mistakes:

• Trying to use relative paths to public/ folder
• Including 'public' in the path
• Using relative paths that break on deployment

4. You see this error when running your Astro project:
Cannot find module './public/image.png'
What is the likely cause based on Astro's project structure?

medium

A. The src/ folder is missing

B. Trying to import a static file from public/ using a relative import

C. The public/ folder is inside src/

D. The image file is corrupted

Solution

1. Step 1: Understand how static files are accessed

   Static files in public/ are not imported via relative paths in code; they are referenced by URL paths.

2. Step 2: Identify the error cause

   Trying to import a file from public/ using a relative import causes this error.

3. Final Answer:

   Trying to import a static file from public/ using a relative import -> Option B

4. Quick Check:

   Static files are referenced by URL, not imported [OK]

Hint: Never import files from public/; use URL paths [OK]

Common Mistakes:

• Importing images or static files as modules
• Placing public/ inside src/
• Assuming public/ files are bundled like code

5. You want to add a new page to your Astro site at URL /about. Where should you place the new file in the project structure?

hard

A. src/pages/about.astro

B. public/about/index.html

C. src/components/about.astro

D. src/about.astro

Solution

1. Step 1: Understand Astro's page routing

   Files inside src/pages/ map directly to site URLs.

2. Step 2: Choose correct location for new page

   Placing about.astro inside src/pages/ creates the /about route.

3. Final Answer:

   src/pages/about.astro -> Option A

4. Quick Check:

   Pages go in src/pages/ folder [OK]

Hint: Put new pages in src/pages/ for routing [OK]

Common Mistakes:

• Placing pages in src/components/
• Adding pages directly in src/ without pages folder
• Putting pages in public/ folder