Astro: Building Fast Content-Focused Sites

# Create a new Astro project (interactive wizard)
npm create astro@latest my-astro-site

# Or scaffold directly with the blog template
npm create astro@latest my-blog -- --template blog

# Navigate into the project
cd my-astro-site

# Start the development server (http://localhost:4321)
npm run dev

# Add React support (auto-configures astro.config.mjs)
npx astro add react

# Add Tailwind CSS
npx astro add tailwind

# Add MDX for interactive Markdown
npx astro add mdx

# Add automatic sitemap generation
npx astro add sitemap

my-astro-site/
├── public/            # Static assets served as-is (images, fonts, favicon)
│   └── favicon.svg
├── src/
│   ├── components/    # Reusable .astro and framework components
│   │   └── Card.astro
│   ├── content/       # Content Collections (Markdown, MDX, JSON, YAML)
│   │   ├── config.ts  # Collection schemas defined here
│   │   └── blog/
│   │       └── first-post.md
│   ├── layouts/       # Page layout wrappers
│   │   └── BaseLayout.astro
│   └── pages/         # File-based routing: every file = a route
│       ├── index.astro         # → /
│       ├── about.astro         # → /about
│       └── blog/
│           └── [slug].astro    # → /blog/:slug (dynamic route)
├── astro.config.mjs   # Framework configuration
├── package.json
└── tsconfig.json

---
// Frontmatter: runs on the server at build time (or per-request in SSR)
// Imports, TypeScript interfaces, and data-fetching logic live here

interface Props {
  title: string;
  description: string;
  pubDate: Date;
  slug: string;
  tags?: string[];
}

const { title, description, pubDate, slug, tags = [] } = Astro.props;

const formattedDate = pubDate.toLocaleDateString('en-US', {
  year: 'numeric', month: 'long', day: 'numeric',
});
---

<!-- Template: HTML with Astro expressions in curly braces -->
<article class="blog-card">
  <a href={`/blog/${slug}`}>
    <h2>{title}</h2>
  </a>
  <time datetime={pubDate.toISOString()}>{formattedDate}</time>
  <p>{description}</p>
  {tags.length > 0 && (
    <ul class="tags">
      {tags.map(tag => <li>{tag}</li>)}
    </ul>
  )}
</article>

<!-- Scoped styles: only apply to THIS component's output -->
<style>
  .blog-card {
    border: 1px solid #e5e7eb;
    border-radius: 8px;
    padding: 24px;
    transition: box-shadow 0.2s;
  }
  .blog-card:hover { box-shadow: 0 4px 12px rgba(0,0,0,0.08); }
  h2 { color: #7c3aed; margin-bottom: 8px; }
  .tags { display: flex; gap: 8px; list-style: none; padding: 0; }
  .tags li { background: #f3f0ff; color: #7c3aed; padding: 2px 10px; border-radius: 12px; font-size: 0.8rem; }
</style>

---
import BaseLayout from '../layouts/BaseLayout.astro';
import BlogCard from '../components/BlogCard.astro';
import Counter from '../components/Counter.jsx';       // React component
import Newsletter from '../components/Newsletter.vue'; // Vue component
import { getCollection } from 'astro:content';

const posts = await getCollection('blog');
---

<BaseLayout title="My Astro Blog">
  <h1>Welcome to My Blog</h1>

  <!-- Static Astro components: pure HTML output, zero JS shipped -->
  <section class="posts-grid">
    {posts.map(post => (
      <BlogCard
        title={post.data.title}
        description={post.data.description}
        pubDate={post.data.pubDate}
        slug={post.slug}
        tags={post.data.tags}
      />
    ))}
  </section>

  <!-- React island: hydrates immediately on page load -->
  <Counter client:load />

  <!-- Vue island: only hydrates when scrolled into the viewport -->
  <Newsletter client:visible />
</BaseLayout>

import { z, defineCollection } from 'astro:content';

const blogCollection = defineCollection({
  type: 'content', // 'content' for Markdown/MDX, 'data' for JSON/YAML
  schema: z.object({
    title: z.string().max(100),
    description: z.string().max(200),
    pubDate: z.coerce.date(),
    updatedDate: z.coerce.date().optional(),
    heroImage: z.string().optional(),
    tags: z.array(z.string()).default([]),
    draft: z.boolean().default(false),
    author: z.string().default('Mayur Dabhi'),
  }),
});

const authorsCollection = defineCollection({
  type: 'data', // JSON or YAML files
  schema: z.object({
    name: z.string(),
    bio: z.string(),
    avatar: z.string().url(),
    twitter: z.string().optional(),
    github: z.string().optional(),
  }),
});

// Export named collections; Astro generates types from this
export const collections = {
  blog: blogCollection,
  authors: authorsCollection,
};

---
import { getCollection, type CollectionEntry } from 'astro:content';
import BaseLayout from '../../layouts/BaseLayout.astro';

// getStaticPaths tells Astro which slugs to pre-render at build time
export async function getStaticPaths() {
  const posts = await getCollection('blog', ({ data }) => {
    return import.meta.env.PROD ? !data.draft : true;
  });

  return posts.map(post => ({
    params: { slug: post.slug },
    props: { post },
  }));
}

type Props = { post: CollectionEntry<'blog'> };
const { post } = Astro.props;

// render() converts Markdown/MDX to an HTML component
const { Content, headings, remarkPluginFrontmatter } = await post.render();
---

<BaseLayout title={post.data.title} description={post.data.description}>
  <article>
    <h1>{post.data.title}</h1>
    <time datetime={post.data.pubDate.toISOString()}>
      {post.data.pubDate.toLocaleDateString()}
    </time>
    {post.data.heroImage && <img src={post.data.heroImage} alt="" />}
    <Content />  {/* Renders the Markdown body as HTML */}
  </article>
</BaseLayout>

---
import SearchBar from '../components/SearchBar.jsx';   // React
import LiveChat from '../components/LiveChat.jsx';     // React
import VideoPlayer from '../components/VideoPlayer.svelte';
import MobileMenu from '../components/MobileMenu.vue';
---

<!-- Hydrates immediately: search must work on first interaction -->
<SearchBar client:load />

<!-- Hydrates when the browser is idle after initial load -->
<LiveChat client:idle />

<!-- Hydrates only when the user scrolls to the video section -->
<VideoPlayer client:visible />

<!-- Hydrates only on mobile screens, saves JS on desktop -->
<MobileMenu client:media="(max-width: 768px)" />

<!-- No directive = renders to HTML only, zero JavaScript shipped -->
<footer><p>© 2026 My Astro Site</p></footer>

import { defineConfig } from 'astro/config';
import react from '@astrojs/react';
import tailwind from '@astrojs/tailwind';
import sitemap from '@astrojs/sitemap';
import vercel from '@astrojs/vercel/serverless'; // SSR on Vercel

export default defineConfig({
  site: 'https://mysite.com',       // Required for sitemap and canonical URLs
  output: 'hybrid',                  // 'static' | 'server' | 'hybrid'
  adapter: vercel(),                 // Required for 'server' or 'hybrid' modes
  integrations: [
    react(),
    tailwind(),
    sitemap(),                       // Auto-generates /sitemap-index.xml
  ],
  image: {
    // Optimise images with Sharp (auto-converts to WebP/AVIF)
    service: { entrypoint: 'astro/assets/services/sharp' },
  },
});

# Build for production (outputs to ./dist/)
npm run build

# Preview the production build locally before deploying
npm run preview

# Deploy static output to Netlify
npx netlify deploy --prod --dir=dist

# Deploy to Vercel (auto-detects Astro, applies correct settings)
npx vercel deploy

# Deploy to Cloudflare Pages
npx wrangler pages deploy dist

---
import { Image, Picture } from 'astro:assets';
import heroImage from '../assets/hero.jpg'; // Local image import
---

<!-- Astro automatically:
     ✓ Converts to WebP/AVIF for smaller file sizes
     ✓ Adds width/height attributes to prevent CLS
     ✓ Adds loading="lazy" and decoding="async"
     ✓ Generates responsive srcset for different screen sizes -->
<Image
  src={heroImage}
  width={800}
  height={400}
  alt="Hero image: describe the content meaningfully"
  format="webp"
  quality={85}
/>

<!-- Picture for art direction with multiple formats -->
<Picture
  src={heroImage}
  formats={['avif', 'webp']}
  width={800}
  height={400}
  alt="Hero image"
/>