LuisLlamas Logo
astrojs-estructura-archivos-carpetas

File and Folder Structure in Astro

  • 4 min
  • Beginner

When you start a project with Astro.js, you’ll see that a quite complete folder structure is generated.

Astro has a opinionated yet flexible folder structure. This means not all Astro projects are identical, and the organization can vary depending on whether you use Markdown, React components, or integrations with Tailwind.

But in general terms, a typical project can have a structure similar to this:

Proyecto/ ├── public/ ├── src/ │ ├── components/ │ ├── layouts/ │ └── pages/ ├── astro.config.mjs ├── package.json └── tsconfig.json

Let’s see what each part does, and how an app is organized in Astro 👇.

Project Root Files

File/DirectoryFunction
astro.config.mjsMain Astro configuration (routes, integrations, build, etc.)
package.jsonProject dependencies, scripts, and metadata
tsconfig.jsonTypeScript configuration (if you use it)
.gitignoreFiles Git should ignore
README.mdProject documentation

At the project root, we have the files that control how Astro behaves.

This is the main configuration file for our project. This is where we configure integrations and build options.

By default, it comes very clean:

import { defineConfig } from 'astro/config';

// https://astro.build/config
export default defineConfig({
  // Here we will put our configurations
});
Copied!

This is the file where:

  1. We will add integrations like Tailwind, React, or Vue.
  2. We will configure whether we want the website to be static (SSG) or server-rendered (SSR).
  3. We will define our final domain (site: 'https://mywebsite.com') for SEO to work correctly.

If you chose TypeScript, these files control typing. Astro automatically generates a .astro/types.d.ts file (which you’ll see referenced).

This gives us intelligent autocompletion even for complex things like content collections, which we’ll see later.

The src/ Folder

This is where we will work 99% of the time. It’s where your source code lives. Astro will process, optimize, and compile everything inside here.

This is the most important folder. Astro uses a file-based routing system.

  • If you create a file src/pages/index.astro, that will be your homepage (/).
  • If you create src/pages/contact.astro, you will automatically have a route at /contact.
  • If you create src/pages/blog/article-1.md, you will have a route at /blog/article-1.

Astro supports .astro, .md, .mdx, .html and even .js/.ts (for API endpoints) files inside the pages folder.

Here we store reusable pieces of code. Buttons, cards, navigation bars…

Unlike pages, files here do not generate automatic routes. They are Lego pieces that we will import inside our pages.

Layouts are a special type of component designed to wrap pages.

For example, here we would create a BaseLayout.astro that contains the <html>, <head>, and <body>. This way we don’t have to repeat meta tags on every page of our website.

The public/ Folder

This is for files that do not need to be processed by Astro and should be copied as-is to the root of the final website.

  • The favicon.svg.
  • The robots.txt file.
  • Images you don’t want Astro to optimize or touch.

Difference between public and src/assets?

If you put an image in public/image.png, you will access it as yoursite.com/image.png. Astro does not touch it.

If you put it in src/assets/, Astro can process it, resize it, and optimize it. Generally, we prefer src/assets for website images.

The .astro File

Before we finish, let’s take a quick look at an .astro file, for example src/pages/index.astro. You’ll see it has a very particular structure:

---
const title = "My first website in Astro";
---

<html lang="es">
  <head>
    <title>{title}</title>
  </head>
  <body>
    <h1>{title}</h1>
    <p>Hello world!</p>
  </body>
</html>
Copied!

This is the syntax of Astro’s component system, which is the core of Astro. We will explore it in greater depth in the following articles.

On this page