Back to Documentation

Astro.js Project Structure Guidelines

This document outlines the recommended structure and organization principles for our Astro.js project. A well-structured project improves maintainability, developer onboarding, and collaboration efficiency.

Project Root Structure

lucasdziura-website/
├── dist/                  # Build output (generated)
├── public/                # Static assets
├── src/                   # Source code
├── .astro/                # Astro cache (generated)
├── node_modules/          # Dependencies (generated)
├── astro.config.mjs       # Astro configuration
├── package.json           # Project manifest
├── tsconfig.json          # TypeScript configuration
├── tailwind.config.mjs    # Tailwind CSS configuration
├── netlify.toml           # Netlify deployment config
├── .gitignore             # Git ignore file
└── README.md              # Project documentation

Source Directory (src/)

The heart of the project:

src/
├── components/            # Reusable UI components
├── content/               # Content collections
├── layouts/               # Page layouts
├── pages/                 # Page components (routes)
├── styles/                # Global styles
└── utils/                 # Utility functions & helpers

Detailed Directory Structure

public/

Store static assets that don't need processing:

public/
├── favicon.ico            # Site favicon
├── robots.txt             # Search engine instructions
├── fonts/                 # Font files
│   ├── inter.woff2
│   └── ...
└── images/                # Static images (not requiring optimization)
    └── ...

src/components/

For reusable components throughout the application:

components/
├── common/                # Shared/generic components
│   ├── Button.astro
│   ├── Card.astro
│   └── ...
├── layout/                # Layout-specific components
│   ├── Header.astro
│   ├── Footer.astro
│   └── ...
├── ui/                    # UI components
│   ├── Carousel.astro
│   ├── Modal.astro
│   └── ...
└── ProjectCard.astro      # Project card component

src/layouts/

For page templates and layouts:

layouts/
├── Layout.astro           # Base layout with common elements
├── ProjectLayout.astro    # Project detail layout
└── ...

src/content/

For content collections:

content/
├── config.ts              # Content collections config
├── art/                   # Art portfolio content
│   ├── project1.md
│   └── ...
├── code/                  # Code portfolio content
│   ├── project1.md
│   └── ...
└── ...

src/styles/

For global styles and theme configuration:

styles/
├── global.css            # Global styles
├── theme.css             # Theme variables
└── ...

src/utils/

For helper functions and utilities:

utils/
├── date.ts               # Date formatting utilities
├── markdown.ts           # Markdown processing helpers
└── ...

Code Organization Best Practices

Component Structure

  1. Single Responsibility: Each component should do one thing well

  2. Cohesive Logic: Group related functionality together

  3. Appropriate Naming: Use descriptive, consistent naming conventions

  4. Component Structure: ```astro

    // 1. Imports import { someHelper } from '../utils/helpers';

    // 2. Component Props interface Props { title: string; description?: string; }

    // 3. Props destructuring const { title, description = 'Default description' } = Astro.props;

    // 4. Data fetching or processing const processedData = someHelper(title);

    {title}

    {description &&

    {description}

    }

File Naming Conventions

  1. Components: Use PascalCase (e.g., ProjectCard.astro)
  2. Pages: Use kebab-case (e.g., about-us.astro)
  3. Utilities: Use camelCase (e.g., formatDate.ts)
  4. Content: Use kebab-case for content files (e.g., my-project.md)

Import Organization

  1. Group imports by type:
    // Third-party libraries first
import { useState } from 'react';

// Astro imports
import { getCollection } from 'astro:content';

// Local components
import Button from '../components/Button.astro';

// Utilities/helpers
import { formatDate } from '../utils/date';

CSS Organization

  1. Component Styles: Use scoped styles within components when possible
  2. Global Styles: Keep global styles minimal
  3. Theme Variables: Use CSS variables for theming
  4. Utility Classes: Leverage Tailwind utility classes when appropriate

Project Scaling Strategies

As the project grows:

  1. Feature Directories: Consider reorganizing by feature rather than type for large applications
  2. Lazy Loading: Implement lazy loading for larger components
  3. Code Splitting: Leverage Astro's automatic code splitting
  4. Documentation: Update documentation as patterns evolve
  5. Refactoring: Periodically assess and refactor areas that have grown organically

References