Skip to content

Template structure

This section is about the file structure. You will learn how the different files are organized, but most important of all, how to manage your project with Astro. Let's dive into the folder structure.

Global structure

bash
root
├── public/
   ├── images/
├── src/
   └── components/
   ├── Component.astro
   ├── data/
   ├── layouts/
   ├── Default.astro
   ├── pages/
   ├── index.astro
   └── styles/
   └── utils/
   └── constants.ts
   └── en.d.ts
   └── types.d.ts
├── astro.config.mjs
└── package.json
└── tailwind.config.cjs
└── tsconfig.json

The directory structure can seem unusual for someone who is not used to build tools. We will break each part of it, so you understand how everything works. You can learn more about Astro project structures on their documentation.

Static assets

bash
root
├── public/
   ├── images/

Astro serves static assets like images, fonts or any type of supported files inside the /public folder. Use this folder to store your project images and any other kind of uncompiled assets that you need in your project.

Layouts folder

bash
root
├── src/
   └── layouts/

Layouts are Astro components used to provide a reusable UI structure, such as a page template. We conventionally use the term Layout for Astro components that provide common UI elements shared across pages such as headers, navigation bars, and footers. A typical Astro layout component provides Astro, Markdown or MDX pages.

But, there is nothing special about a layout component! They can accept props and import and use other components like any other Astro component. They can include UI frameworks components and client-side scripts. They do not even have to provide a full page shell, and can instead be used as partial UI templates.

Layout components are commonly placed in a src/layouts directory in your project for organization, but this is not a requirement.

The layouts folder holds all the template layouts. It is mandatory to have at least one layout, and it should always be named Default.astro. Additional layouts can have the names you want, but don't forget the .astro extension. Also notice the <slot /> tag that is present in each layout file. This is a reference to append the rest of the page content.

Using a layout in a page

The layouts/ folder can hold one or more layout files. But generally, you'll find one or two in there like Default.astro. Layouts are nothing more than Astro components. Inside a page like src/pages/index.astro, you can use a layout like this:

html
---
import Layout from '@layouts/Default.astro'
---
<Layout>
  <!-- Your page content goes in here -->
</Layout>

You can learn more about Astro layouts by reading their documentation.

Pages folder

bash
root
├── src/
   └── pages/

The pages folder holds all the template pages. Pages are focused on content. Pages are files that live in the src/pages/ sub-directory of your Astro project. They are responsible for handling routing, data loading, and overall page layout for every page in your website. You will sometimes find a particular statement at the top of Astro pages code :

html
---
import Layout from '@layouts/Default.astro'
import Navbar from '@components/Navbar.astro'
---

In each .astro file, you can open a special area between a --- and a ---. Inside that area, everything you write is treated and processed as javascript. You can import functions, components and declare variables.

Page files

Your project pages live in this folder. They all have a .astro extensions. Astro also support other types of files for pages. .astro, .md, .mdx and .html extensions are supported. You can learn more about Astro pages by reading their documentation.

Components folder

bash
root
├── src/
   └── components/

The components folder holds all your reusable HTML components. Components are chunks of code that you want to reuse as is across your application : it can be a button, a navbar, a content section or whatever you want. Note that you can create as many sub-folders as you want to organize your components. Components are named like page files, but in Camel case : Navbar.astro. When you want to call a component in one of your layouts or pages, you first need to import it:

html
---
import Navbar from '@components/Navbar.astro'
---

You can then use the component in your page like this:

html
<Layout>
  <Navbar />
</Layout>

Astro components behave like components from advanced frameworks like Vue and React. They can instantiate and use variables, define and use props, fetch data and many more things that make Astro such a complete and solid framework. You can learn more about Astro components by reading their documentation.

Styles

root
├── src/
│   ├── styles/
│   │   └── global.scss

This template relies on the powerful Tailwind CSS features, letting you handle complex styles in a breeze. The project provides a base SCSS file with the basi Taiwlind CSS setup. The global.scss file is the main entry point for all your styles. You can import other SCSS files in this one, and they will be compiled to CSS.

Root files

There also a few files sitting at the root of the project that we need to discuss before getting into serious business:

  • astro.config.mjs : The main Astro configuration file.
  • package.json : Lists all your project's dependencies and gives useful metadata.
  • tailwind.config.cjs : The main Tailwind CSS configuration file.

All Rights Reserved