# Astro Builder > Comprehensive skill for building websites with Astro.build. Use when the user wants to create a website using Astro, needs to select an appropriate theme from Astro's free themes collection, requires access to Astro documentation, or wants to develop Astro components and pages. This skill handles theme selection, documentation access, project setup, and Astro-specific development patterns including islands architecture, content collections, and view transitions. - Skill: `mhdcodes/astro-builder` (Agent Skill) - Install (CLI): `npx skillmds@latest add mhdcodes/astro-builder` - Raw SKILL.md: https://api.skillmd.com/api/skills/mhdcodes/astro-builder/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Web & Frontend - Author: mhdcodes (https://skillmd.com/u/mhdcodes) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/mhdcodes/astro-builder --- # Astro Website Builder This skill helps you build websites with Astro.build by guiding you through theme selection, documentation access, and development best practices. Use this skill whenever a user mentions building with Astro, wants to create a website, or needs help with Astro-specific features. ## When to Use This Skill Activate this skill when: - User mentions "Astro" or "astro.build" in their request - User wants to build a website and Astro would be appropriate (blogs, documentation, portfolios, marketing sites, content-driven sites) - User needs to select a theme for their Astro project - User needs help with Astro components, routing, islands architecture, or configuration - User wants to integrate React, Vue, Svelte, Solid, or other frameworks with Astro - User needs access to Astro's documentation or best practices - User wants to implement content collections, view transitions, or server islands ## Core Astro Concepts ### Islands Architecture Astro pioneered the **islands architecture** pattern: - Pages render as static HTML by default (zero JavaScript) - Interactive components become "islands" of interactivity - Use `client:*` directives to hydrate specific components - Available directives: `client:load`, `client:idle`, `client:visible`, `client:media` - Multiple framework islands can coexist on the same page ### Server-First Approach - Astro is a **Multi-Page App (MPA)** framework, not an SPA - Rendering happens on the server (build-time or on-demand) - Results in 40% faster load times with 90% less JavaScript vs typical SPAs - Client-side interactivity is opt-in, not mandatory ### Server Islands (New Feature) - Use `server:defer` directive on Astro components for deferred server rendering - Allows personalized/dynamic content without blocking page load - Combines static HTML with dynamic server-generated components - Perfect for user avatars, personalized content, or slow API calls ## Workflow Overview When building an Astro website, follow this process: 1. **Understand Requirements** - Determine the type of website and features needed 2. **Select Appropriate Theme** - Choose from Astro's free themes based on requirements 3. **Access Documentation** - Reference Astro docs for specific features 4. **Initialize Project** - Set up the project structure 5. **Develop Components** - Build using Astro's component architecture 6. **Add Interactivity** - Implement islands for client-side functionality 7. **Optimize & Deploy** - Follow best practices for performance ## Step 1: Understand Requirements First, identify the type of website and its requirements: **Website Types Best Suited for Astro:** - Blog/Publication site (excellent fit) - Portfolio/Showcase (excellent fit) - Documentation site (use Starlight) - Marketing/Landing page (excellent fit) - E-commerce site (good fit) - Company/Business site (excellent fit) - Personal website (excellent fit) - Community sites - Any content-driven website **Key Questions to Ask:** - What is the primary purpose of the site? - What content types will it have? (blog posts, projects, products, etc.) - Does it need interactivity? (forms, search, dynamic content) - What frameworks does the user prefer? (React, Vue, Svelte, Solid, Preact, etc.) - Does it need specific features? (dark mode, i18n, CMS integration, view transitions) - Will content be managed via content collections or a headless CMS? - Does it need on-demand rendering or is static generation sufficient? ## Step 2: Select Appropriate Theme Use web_fetch to browse free themes with appropriate filters: **Base URL for themes:** ``` https://astro.build/themes/1/ ``` **Available filters:** - Technology: `?technology[]=react`, `technology[]=vue`, `technology[]=svelte`, `technology[]=tailwind` - Price: `?price[]=free`, `price[]=premium` - Features: Content collections, dark mode, i18n, etc. **Example fetches:** ``` # Free React-compatible themes https://astro.build/themes/1/?search=&technology%5B%5D=react&price%5B%5D=free # Free Tailwind themes https://astro.build/themes/1/?search=&technology%5B%5D=tailwind&price%5B%5D=free # All free themes https://astro.build/themes/1/?price%5B%5D=free ``` **Theme Selection Criteria:** For **Blogs/Publications**: - Look for content collections support - Strong typography and reading experience - Must support Markdown/MDX - Should have tags/categories - RSS feed support - Consider: astro-paper, astro-blog-template For **Portfolios**: - Visual project showcase capabilities - About/Contact sections - Smooth animations and transitions - Image optimization - Consider themes with view transitions For **Documentation**: - **Strongly recommend Starlight** (official Astro docs framework) - Features: Built-in search, sidebar navigation, dark mode, i18n - Best for: Technical docs, API references, guides - Installation: `npm create astro@latest -- --template starlight` For **Landing Pages**: - Hero section with CTA - Features/Benefits sections - Contact forms - Conversion-optimized design - Fast loading for better SEO For **E-commerce**: - Product listings and filters - Shopping cart functionality - Payment integration ready - Product detail pages - Content collections for products **Action:** Fetch the themes page, analyze available themes, and recommend 2-3 options that best match the user's requirements. Explain why each theme is suitable and highlight key features. ## Step 3: Access Astro Documentation **Documentation Hierarchy:** 1. **Built-in Reference (First Priority)**: `references/astro_docs.md` - Contains core Astro concepts, syntax, and common patterns - READ THIS FIRST for most questions 2. **Full LLM-Optimized Docs**: `https://docs.astro.build/llms-full.txt` - Comprehensive, LLM-friendly format - Use for advanced features and detailed reference 3. **Web Documentation**: `https://docs.astro.build` - Official docs site - Use for latest updates or visual guides **When to Reference Documentation:** - Component syntax questions → Reference astro_docs.md - Routing and pages → Reference astro_docs.md - Styling options → Reference astro_docs.md - Islands architecture → Fetch LLM docs or reference built-in docs - Content collections → Fetch LLM docs - View transitions → Fetch LLM docs - Server islands → Fetch LLM docs - Integration setup → Fetch LLM docs - Advanced configuration → Fetch LLM docs - API details → Fetch LLM docs ## Step 4: Initialize Astro Project ### Using Create Astro CLI (Recommended) **Standard new project:** ```bash npm create astro@latest ``` **With specific template:** ```bash npm create astro@latest -- --template / ``` **With Starlight (for documentation):** ```bash npm create astro@latest -- --template starlight ``` **With integrations pre-installed:** ```bash npm create astro@latest -- --add react --add partytown ``` **Supported integrations for `--add` flag:** - Framework integrations: `react`, `preact`, `vue`, `svelte`, `solid` - Other integrations: `tailwind`, `partytown`, `mdx`, `sitemap` ### Prerequisites **Node.js version requirements:** - `v18.20.8` or higher - `v20.3.0` or higher - `v22.0.0` or higher - Note: `v19` and `v21` are NOT supported **Recommended tools:** - VS Code with [Official Astro extension](https://marketplace.visualstudio.com/items?itemName=astro-build.astro-vscode) - Terminal for CLI access ### Project Structure Setup After initialization, ensure proper structure: ``` project/ ├── src/ │ ├── components/ # Reusable components │ ├── layouts/ # Page layouts │ ├── pages/ # Routes (REQUIRED - file-based routing) │ │ ├── index.astro # Homepage (/) │ │ ├── about.astro # About page (/about) │ │ ├── blog/ │ │ │ └── [...slug].astro # Dynamic blog routes │ │ ├── 404.astro # Custom 404 page │ │ └── 500.astro # Custom 500 page (on-demand rendering only) │ ├── content/ # Content collections (recommended for blogs) │ │ └── config.ts # Content collections config │ ├── assets/ # Optimized images and assets │ └── styles/ # Global styles (optional) ├── public/ # Static assets (copied as-is) │ ├── favicon.svg │ └── robots.txt ├── astro.config.mjs # Astro configuration ├── package.json # Dependencies and scripts └── tsconfig.json # TypeScript config ``` **Critical Notes:** - The `src/pages/` directory is **REQUIRED** for routing to work - Only `src/pages/` is a reserved directory - others are conventional but optional - Files in `public/` are served as-is (not processed or optimized) - Files in `src/` are processed, optimized, and bundled ## Step 5: Develop Components and Pages ### Astro Component Structure Every Astro component has two parts: 1. **Component Script** (Frontmatter) - between `---` fences 2. **Component Template** - HTML with Astro syntax **Basic component example:** ```astro --- // Component Script - runs at build time (server-side) // Import other components import Button from './Button.astro'; // Define props with TypeScript interface Props { title: string; description?: string; } const { title, description = "Default description" } = Astro.props; // Fetch data (this is safe - runs server-side only) const data = await fetch('API_URL').then(r => r.json()); ---

{title}

{description &&

{description}

}
``` ### Component Development Best Practices 1. **Props with TypeScript:** ```astro --- interface Props { title: string; count?: number; items: string[]; } const { title, count = 0, items } = Astro.props; --- ``` 2. **Default values:** ```astro --- const { greeting = "Hello", name = "Astronaut" } = Astro.props; --- ``` 3. **Component imports:** ```astro --- import Layout from '../layouts/Layout.astro'; import Card from '../components/Card.astro'; import { Icon } from 'astro-icon'; --- ``` ### Slots for Component Composition **Default slot:** ```astro
``` **Named slots:** ```astro
``` **Using named slots:** ```astro

My Site

Main content here

© 2026

 ``` **Slot fallback content:** ```astro

This shows if no content is provided

 ``` ### Page Development Pattern **Simple page:** ```astro --- import Layout from '../layouts/Layout.astro'; const title = "My Page"; ---

{title}

Content here

 ``` **Page with data fetching:** ```astro --- import Layout from '../layouts/Layout.astro'; const response = await fetch('https://api.example.com/data'); const data = await response.json(); ---
    {data.map(item => (
  • {item.name}
    • ))}
``` **Dynamic route with getStaticPaths:** ```astro --- // src/pages/blog/[slug].astro export async function getStaticPaths() { const posts = await fetchBlogPosts(); return posts.map(post => ({ params: { slug: post.slug }, props: { post } })); } const { post } = Astro.props; ---

{post.title}

{post.content}

``` ## Step 6: Adding Interactivity with Islands ### The Islands Pattern By default, **ALL components render to static HTML with zero JavaScript**. To add interactivity: 1. **Install framework integration:** ```bash npx astro add react # or npx astro add vue # or npx astro add svelte # or npx astro add solid # or npx astro add preact ``` 2. **Create framework component:** ```jsx // src/components/Counter.jsx import { useState } from "react"; export default function Counter() { const [count, setCount] = useState(0); return ; } ``` 3. **Use with client directive:** ```astro --- import Counter from '../components/Counter.jsx'; --- ``` ### Client Directives Explained - **`client:load`** - Hydrate immediately on page load (high priority) - **`client:idle`** - Hydrate when browser is idle (recommended for most) - **`client:visible`** - Hydrate when component enters viewport (best for below-fold) - **`client:media="(query)"`** - Hydrate when media query matches - **`client:only="framework"`** - Skip server rendering, client-side only **Performance tip:** Use `client:idle` or `client:visible` by default. Only use `client:load` for critical interactive elements. ### Server Islands (New Feature) For dynamic server-rendered content that can load after the main page: ```astro --- import UserAvatar from '../components/UserAvatar.astro'; import RecentPosts from '../components/RecentPosts.astro'; ---

Welcome!

``` ## Step 7: Content Collections (Recommended for Blogs) Content collections provide type-safe content management: **1. Define schema in `src/content/config.ts`:** ```typescript import { defineCollection, z } from "astro:content"; const blog = defineCollection({ type: "content", schema: z.object({ title: z.string(), description: z.string(), publishDate: z.date(), tags: z.array(z.string()), image: z.string().optional(), }), }); export const collections = { blog }; ``` **2. Create content in `src/content/blog/`:** ```markdown --- title: "My First Post" description: "This is my first blog post" publishDate: 2026-02-06 tags: ["astro", "blogging"] --- Content here in Markdown! ``` **3. Query in pages:** ```astro --- import { getCollection } from 'astro:content'; const blogPosts = await getCollection('blog'); const sortedPosts = blogPosts.sort((a, b) => b.data.publishDate.valueOf() - a.data.publishDate.valueOf() ); --- {sortedPosts.map(post => ( ))} ``` **4. Render individual posts:** ```astro --- // src/pages/blog/[...slug].astro import { getCollection } from 'astro:content'; export async function getStaticPaths() { const posts = await getCollection('blog'); return posts.map(post => ({ params: { slug: post.slug }, props: { post }, })); } const { post } = Astro.props; const { Content } = await post.render(); ---

{post.data.title}

``` ## Step 8: View Transitions Add smooth page transitions with minimal code: **1. Add to layout:** ```astro --- import { ViewTransitions } from 'astro:transitions'; --- ``` **2. Customize transitions on elements:** ```astro

Title

``` **3. Control transition behavior:** ```astro --- // Disable transitions for this page export const transitionDisable = true; --- ``` ## Configuration & Optimization ### Essential Astro Config Options ```javascript // astro.config.mjs import { defineConfig } from "astro/config"; import react from "@astrojs/react"; import tailwind from "@astrojs/tailwind"; export default defineConfig({ // Site URL for sitemaps and canonical URLs site: "https://example.com", // Base path if deploying to subdirectory base: "/docs", // Trailing slash preference trailingSlash: "always", // or 'never' or 'ignore' // Output mode output: "static", // or 'server' or 'hybrid' // Integrations integrations: [react(), tailwind()], // Image optimization image: { domains: ["example.com"], }, // Markdown options markdown: { shikiConfig: { theme: "dracula", }, }, }); ``` ### Performance Best Practices 1. **Keep islands minimal:** - Only use `client:*` directives when truly needed - Prefer static HTML whenever possible - Use `client:idle` or `client:visible` over `client:load` 2. **Optimize images:** ```astro --- import { Image } from 'astro:assets'; import heroImage from '../assets/hero.jpg'; --- Hero ``` 3. **Use content collections for type safety:** - Define schemas for all content - Get autocomplete and type checking - Validate content at build time 4. **Implement proper caching headers:** - Configure in your hosting platform - Use aggressive caching for static assets 5. **Minimize client-side JavaScript:** - Astro's default is zero JS - keep it that way - Only add interactivity where needed - Consider using `