🚀 Building with Astro: A Developer's Quickstart Guide

Astro Project Guide

Astro is cool. I am using it to build this website. Kickstart your Astro journey with this curated guide featuring project setup instructions, helpful resources, and best practices for structuring layouts and components. Whether you’re creating a blog, portfolio, or complex frontend app, this guide offers everything you need to build fast, modern websites using Astro.

🚀 Shoutouts & Resources

Huge thanks to Mark Horn for creating the awesome Astro Sphere project!
🛠️ Neovim config for AstroJS: Check out this Medium article for a smooth dev experience.
📺 Learn Astro from scratch via this Frontend Masters course.

⚙️ Getting Started

Quick commands to launch an Astro project:

npm create astro       # Create a new Astro project
npm run dev            # Start the development server
gh repo clone learnwithjason/astro-frontend-masters -- -b start  # Clone starter repo

✍️ Sample Blog Example

Want to see a real-world Astro blog? Check out:

🗂️ Project Structure

Astro encourages a clean, opinionated project layout. Here’s what your project tree might look like:

├── README.md              # Project documentation
├── astro.config.mjs       # Astro configuration
├── package.json           # Project metadata & scripts
├── public/                # Static files (images, CSS, JS, fonts)
├── src/                   # Source code
│   ├── components/        # Reusable UI components
│   ├── layouts/           # Page templates
│   ├── pages/             # Route-based pages
│   └── styles/            # CSS/Sass files
└── yarn.lock              # Lock file for dependencies (if using yarn)

🧩 Key Directories Explained

public/: Static files served as-is (great for favicons, images, etc).
src/components/: UI building blocks. Use .astro, React, Vue, etc.
src/layouts/: Page templates with shared structure like headers/footers.
src/pages/: File-based routing. index.astro → /, about.astro → /about
src/styles/: Style sheets (global or scoped).
astro.config.mjs & package.json: Project configuration & scripts.

🧱 Layouts in Astro

Layouts make your page structure consistent and maintainable. Store them in src/layouts/.

Example: Site Layout

---
// src/layouts/SiteLayout.astro
import Header from '../components/Header.astro';
import Footer from '../components/Footer.astro';
---
<html lang="en">
  <head>
    <Header />
  </head>
  <body>
    <slot /> <!-- Page content injected here -->
    <Footer />
  </body>
</html>

Using the Layout in a Page

---
// src/pages/index.astro
import SiteLayout from '../layouts/SiteLayout.astro';
---
<SiteLayout>
  <p>Welcome to my Astro site!</p>
</SiteLayout>

🔧 Advanced: Named Slots for Layouts

Want to pass content into specific layout sections? Use named slots!

Layout with Named Slots

---
// src/layouts/MyLayout.astro
---
<slot name="header" />
<main>
  <slot /> <!-- Default content -->
</main>
<footer>
  <slot name="footer" />
</footer>

Using Named Slots in a Page

---
// src/pages/index.astro
import MyLayout from '../layouts/MyLayout.astro';
---
<MyLayout>
  <div slot="header">Header content</div>
  <div>Main content goes here</div>
  <div slot="footer">Footer content</div>
</MyLayout>

Happy building with Astro! 🚀