astro

Astro Best Practices

Astro is a "disappearing" framework designed for shipping zero JavaScript by default, adding interactivity only where needed. Our team leverages Astro for its unparalleled performance and developer experience, especially for content-focused sites. Adhere to these guidelines to maintain a consistent, high-performing, and maintainable codebase.

1. Code Organization and Structure

Maintain a predictable and logical file structure for easy navigation and scaling.

1.1 Standard Project Structure

Always scaffold new projects with the official Astro starter and maintain the following structure:

src/
├── components/ # Reusable UI components (Astro or UI framework islands)
│   ├── ui/ # Generic, framework-agnostic components
│   └── react/ # React-specific components
├── content/ # Markdown/MDX files for Content Collections
├── layouts/ # Base page layouts
├── pages/ # Top-level routes
├── styles/ # Global CSS, utility classes, Tailwind config
├── env.d.ts # Global type declarations
└── astro.config.ts # Type-safe Astro configuration

1.2 Naming Conventions

• Astro Components (.astro): Use kebab-case.
• UI Framework Components (e.g., React .jsx, .tsx): Use PascalCase.
• Pages (.astro): Use kebab-case for file names.

❌ BAD

<!-- src/components/MyCard.astro -->
<div class="myCard">...</div>

// src/components/Mycard.jsx
export default function Mycard() { return <div>...</div>; }

✅ GOOD

<!-- src/components/my-card.astro -->
<div class="my-card">...</div>

// src/components/react/MyCard.tsx
export default function MyCard() { return <div>...</div>; }

1.3 TypeScript Configuration

Leverage TypeScript throughout the codebase for type safety, even in .astro components.

tsconfig.json

{
  "extends": "astro/tsconfigs/strict",
  "compilerOptions": {
    "verbatimModuleSyntax": true, // Enforce explicit type imports
    "plugins": [
      {
        "name": "@astrojs/ts-plugin" // Essential for editor support
      }
    ],
    "paths": {
      "@components/*": ["./src/components/*"],
      "@layouts/*": ["./src/layouts/*"],
      "@content/*": ["./src/content/*"],
      "@styles/*": ["./src/styles/*"]
    }
  },
  "include": [".astro/types.d.ts", "**/*"],
  "exclude": ["dist"]
}