Astro Setup

# Astro 5.x Project Setup Playbook

Production-tested patterns from the ActiveWizards site build (147 pages, 115 blog posts, 12 case studies, 5 service pages). Every code example is extracted from a running production site.

Project Initialization

Tailwind v4 Integration

Content Collections

Layout Hierarchy

Core Components

Global CSS with @theme Tokens

1. Project Initialization

``bash


npm create astro@latest my-site



Recommended options:
Template: Empty (start clean, not a starter)
TypeScript: Yes, strict
Install dependencies: Yes

After scaffolding:

`bash


cd my-site
npm install tailwindcss @tailwindcss/vite @astrojs/sitemap
npm install astro-robots-txt astro-compress astro-expressive-code
npm install astro-icon astro-pagefind
npm install rehype-slug rehype-autolink-headings rehype-external-links
npm install remark-reading-time mdast-util-to-string
npm install medium-zoom

Production package.json dependencies (proven stable):

`json


{
  "name": "site-aw",
  "type": "module",
  "version": "0.0.1",
  "scripts": {
    "dev": "astro dev",
    "build": "astro build",
    "preview": "astro preview",
    "astro": "astro"
  },
  "dependencies": {
    "@astrojs/check": "^0.9.6",
    "@astrojs/rss": "^4.0.15",
    "@astrojs/sitemap": "^3.7.0",
    "@tailwindcss/vite": "^4.2.1",
    "astro": "^5.17.1",
    "astro-compress": "^2.3.9",
    "astro-expressive-code": "^0.41.7",
    "astro-icon": "^1.1.5",
    "astro-pagefind": "^1.8.5",
    "astro-robots-txt": "^1.0.0",
    "mdast-util-to-string": "^4.0.0",
    "medium-zoom": "^1.1.0",
    "rehype-autolink-headings": "^7.1.0",
    "rehype-external-links": "^3.0.0",
    "rehype-slug": "^6.0.0",
    "remark-reading-time": "^2.0.2",
    "tailwindcss": "^4.2.1"
  }
}





2. Tailwind v4 Integration

Tailwind v4 uses Vite plugin instead of PostCSS. No tailwind.config.js needed — tokens go in CSS @theme blocks.



Do NOT use

@astrojs/tailwind.

 Use the Vite plugin directly:

`bash


npm install tailwindcss @tailwindcss/vite

In astro.config.mjs:

`js


import tailwindcss from '@tailwindcss/vite';

export default defineConfig({
  vite: {
    plugins: [tailwindcss()],
  },
});

In src/styles/global.css:

`css


@import "tailwindcss";

@theme {
  --color-bg-primary: #0A0A0F;
  --color-text-primary: #EDEDED;
  --color-accent: #00D4AA;
  --font-sans: 'Geist Sans', system-ui, sans-serif;
  --font-mono: 'Geist Mono', monospace;
}



Import the CSS in your base layout:

`astro



import '../styles/global.css';



Key difference from Tailwind v3: No

tailwind.config.js. All tokens live in CSS @theme blocks. Utility classes reference tokens via var() — e.g., bg-[var(--color-bg-primary)]

.



3. Content Collections

Astro 5.x uses src/content.config.ts (not src/content/config.ts from v4).

src/content.config.ts

`ts


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

const blog = defineCollection({
  loader: glob({ pattern: '**/*.md', base: './src/content/blog' }),
  schema: z.object({
    title: z.string(),
    description: z.string(),
    publishedAt: z.coerce.date(),
    updatedAt: z.coerce.date().optional(),
    tags: z.array(z.string()).default([]),
    // GEO fields (for Generative Engine Optimization)
    problem: z.string().optional(),
    technology: z.string().optional(),
    technologyVersion: z.string().optional(),
    persona: z.string().optional(),
    // SEO overrides
    metaTitle: z.string().optional(),
    metaDescription: z.string().optional(),
    ogImage: z.string().optional(),
    // Content
    tldr: z.string().optional(),
    relatedPosts: z.array(z.string()).default([]),
    readingTime: z.number().optional(),
  }),
});

const cases = defineCollection({
  loader: glob({ pattern: '**/*.md', base: './src/content/cases' }),
  schema: z.object({
    title: z.string(),
    description: z.string(),
    publishedAt: z.coerce.date(),
    client: z.string().optional(),
    industry: z.string().optional(),
    technologies: z.array(z.string()).default([]),
    metrics: z.array(z.object({
      label: z.string(),
      value: z.string(),
    })).default([]),
    image: z.string().optional(),
    metaTitle: z.string().optional(),
    metaDescription: z.string().optional(),
  }),
});

const services = defineCollection({
  loader: glob({ pattern: '**/*.md', base: './src/content/services' }),
  schema: z.object({
    title: z.string(),
    description: z.string(),
    icon: z.string().optional(),
    order: z.number().default(0),
    technologies: z.array(z.string()).default([]),
    caseStudies: z.array(z.string()).default([]),
    metaTitle: z.string().optional(),
    metaDescription: z.string().optional(),
  }),
});

export const collections = { blog, cases, services };



Content file structure


src/content/
  blog/
    my-first-post.md
    another-post.md
  cases/
    project-alpha.md
  services/
    ai-agent-engineering.md



Frontmatter example (blog)

`yaml



title: "Building Production RAG Pipelines with LangChain"
description: "A complete guide to deploying retrieval-augmented generation in production."
publishedAt: 2025-11-15
updatedAt: 2026-01-20
tags: ["RAG", "LangChain", "Vector DB"]
problem: "How to build a production RAG pipeline"
technology: "LangChain"
technologyVersion: "0.3.x"
tldr: "
Use chunking with overlap
Embed with ada-002
"


Article body in Markdown...



Key patterns

Use z.coerce.date() for dates — handles both 2025-11-15 and "2025-11-15T00:00:00Z" strings

Use .default([]) for array fields to avoid undefined checks everywhere

Use .optional() for fields that not every post will have

The glob loader in v5 replaces the implicit directory-based loader from v4





4. Layout Hierarchy


BaseLayout (HTML shell, SEO, fonts, Nav, Footer)
  └── BlogLayout (article header, TL;DR, article body, CTA, related posts)
  └── CaseStudyLayout (metrics bar, hero image, prose body)
  └── [page].astro (direct use for index pages, about, contact)

`BaseLayout —` src/layouts/BaseLayout.astro



The HTML shell. Every page uses this.

`astro



import '../styles/global.css';
import Nav from '../components/Nav.astro';
import Footer from '../components/Footer.astro';
import SEO from '../components/SEO.astro';

export interface Props {
  title: string;
  description: string;
  canonical?: string;
  ogImage?: string;
  ogType?: 'website' | 'article';
  publishedAt?: Date;
  updatedAt?: Date;
  jsonLd?: Record;
}

const props = Astro.props;





  
  
  

  

  
  
  



  

    Skip to content

`BlogLayout —` src/layouts/BlogLayout.astro



Wraps BaseLayout with article-specific structure:

`astro



import BaseLayout from './BaseLayout.astro';

export interface Props {
  title: string;
  description: string;
  publishedAt: Date;
  updatedAt?: Date;
  tags?: string[];
  tldr?: string;
  readingTime?: number;
  ogImage?: string;
  relatedPosts?: any[];
}

const {
  title, description, publishedAt, updatedAt,
  tags = [], tldr, readingTime, ogImage, relatedPosts = [],
} = Astro.props;

const canonicalUrl = new URL(Astro.url.pathname, 'https://yoursite.com').href;
const pubDate = publishedAt.toISOString().split('T')[0];

// Build JSON-LD for TechArticle
const jsonLd = {
  '@context': 'https://schema.org',
  '@type': 'TechArticle',
  headline: title,
  description,
  url: canonicalUrl,
  datePublished: publishedAt.toISOString(),
  ...(updatedAt && { dateModified: updatedAt.toISOString() }),
  author: { '@type': 'Person', name: 'Your Name' },
  publisher: { '@type': 'Organization', name: 'Your Org' },

...(readingTime && { timeRequired: PT${readingTime}M }),


  ...(tags.length > 0 && { keywords: tags.join(', ') }),
};

title={${title} | Your Site}


  description={description}
  ogType="article"
  ogImage={ogImage}
  publishedAt={publishedAt}
  jsonLd={jsonLd}
>
  
  

    Home / Blog / {title}


    
{title}

{pubDate} {readingTime && · ${readingTime} min read}



  
  {tldr && 
}

  
  

    
  


  
  {relatedPosts.length > 0 && (
    

      {relatedPosts.map((rp) => (
        /blog/${rp.id}/}>{rp.data.title}

      ))}
    

  )}

`




5. Core Components

SEO Component — src/components/SEO.astro


`astro


export interface Props {
  title: string;
  description: string;
  canonical?: string;
  ogImage?: string;
  ogType?: 'website' | 'article';
  publishedAt?: Date;
  updatedAt?: Date;
  jsonLd?: Record;
}

const {
  title, description, canonical,
  ogImage = '/images/og-default.png',
  ogType = 'website',
  publishedAt, updatedAt, jsonLd,
} = Astro.props;

const siteUrl = 'https://yoursite.com';
const canonicalUrl = canonical || new URL(Astro.url.pathname, siteUrl).href;
const ogImageUrl = ogImage.startsWith('http') ? ogImage : new URL(ogImage, siteUrl).href;

const baseJsonLd = jsonLd || {
  '@context': 'https://schema.org',
  '@type': 'WebPage',
  name: title,
  description,
  url: canonicalUrl,
  publisher: { '@type': 'Organization', name: 'Your Org', url: siteUrl },
};



{title}



















{publishedAt && }
{updatedAt && }



`


Footer Component — src/components/Footer.astro


`astro


const currentYear = new Date().getFullYear();



  

    
    

      YourBrand
      
Your tagline here.

    


    
    

      Services
      Service One
      Service Two
    


    

      Company
      Blog
      About
      Contact
    

  


  

    
      © {currentYear} YourBrand
    
    

      Privacy
      Terms
    

  


`




6. Global CSS with @theme Tokens

The @theme block is Tailwind v4's replacement for tailwind.config.js. Place in src/styles/global.css:


`css

@import "tailwindcss";

@theme {
  /* Colors */
  --color-bg-primary: #0A0A0F;
  --color-bg-secondary: #111118;
  --color-bg-tertiary: #1A1A24;
  --color-text-primary: #EDEDED;
  --color-text-secondary: #9CA3AF;
  --color-text-muted: #8B8B96;
  --color-accent: #00D4AA;
  --color-accent-hover: #00F5C8;
  --color-border: rgba(255, 255, 255, 0.06);

  /* Typography */
  --font-sans: 'Geist Sans', system-ui, sans-serif;
  --font-mono: 'Geist Mono', monospace;

  /* Spacing */
  --max-width-container: 1280px;
  --max-width-narrow: 680px;

  /* Border radius */
  --radius-none: 0;
  --radius-sm: 2px;
  --radius-DEFAULT: 4px;
}

/* Global reset — zero shadows for brutalist aesthetic */
*, *::before, *::after {
  box-shadow: none !important;
  text-shadow: none !important;
}

html {
  background-color: var(--color-bg-primary);
  color: var(--color-text-primary);
  font-family: var(--font-sans);
  -webkit-font-smoothing: antialiased;
}

/* Prose (article body) */
.prose {
  max-width: var(--max-width-narrow);
  color: var(--color-text-secondary);
  line-height: 1.7;
}

.prose h1, .prose h2, .prose h3 {
  color: var(--color-text-primary);
  font-weight: 700;
}

.prose h2 {
  font-size: 2rem;
  margin-top: 3rem;
  margin-bottom: 1.5rem;
  padding-bottom: 0.75rem;
  border-bottom: 1px solid var(--color-border);
}

.prose a {
  color: var(--color-accent);
}

/* Scroll animation */
.fade-in-up {
  opacity: 0;
  transform: translateY(20px);
  transition: opacity 0.6s ease, transform 0.6s ease;
}
.fade-in-up.visible {
  opacity: 1;
  transform: translateY(0);
}
`




7. Dynamic Routes

Blog post route — src/pages/blog/[...slug].astro


`astro


import { getCollection, render } from 'astro:content';
import BlogLayout from '../../layouts/BlogLayout.astro';

export async function getStaticPaths() {
  const posts = await getCollection('blog');
  return posts.map((post) => ({
    params: { slug: post.id },
    props: { post, allPosts: posts },
  }));
}

const { post, allPosts } = Astro.props;
const { Content } = await render(post);

// Related posts: tag-based matching
const currentTags = new Set(post.data.tags.map((t: string) => t.toLowerCase()));
const relatedPosts = allPosts
  .filter((p: any) => p.id !== post.id)
  .map((p: any) => ({
    post: p,
    score: p.data.tags.filter((t: string) => currentTags.has(t.toLowerCase())).length,
  }))
  .filter((r: any) => r.score > 0)
  .sort((a: any, b: any) => b.score - a.score || b.post.data.publishedAt.getTime() - a.post.data.publishedAt.getTime())
  .slice(0, 3)
  .map((r: any) => r.post);



  title={post.data.title}
  description={post.data.description}
  publishedAt={post.data.publishedAt}
  updatedAt={post.data.updatedAt}
  tags={post.data.tags}
  tldr={post.data.tldr}
  readingTime={post.data.readingTime}
  ogImage={post.data.ogImage}
  relatedPosts={relatedPosts}
>
  

`


Key patterns:
Use [...slug].astro (rest params) for clean URLs without leading slash issues

Pass allPosts via props to compute related posts without a second getCollection() call

Use render(post) to get the  component (Astro 5 API — replaces post.render())

Related post scoring: count overlapping tags, break ties by date

Case study route — src/pages/case-studies/[...slug].astro


Same pattern, different collection:

`astro

export async function getStaticPaths() {
  const cases = await getCollection('cases');
  return cases.map((c) => ({
    params: { slug: c.id },
    props: { caseStudy: c },
  }));
}
`




8. Pagination

Manual pagination — src/pages/blog/[page].astro


`astro


import BaseLayout from '../../layouts/BaseLayout.astro';
import { getCollection } from 'astro:content';

export async function getStaticPaths() {
  const POSTS_PER_PAGE = 12;
  const allPosts = await getCollection('blog');
  const totalPages = Math.ceil(allPosts.length / POSTS_PER_PAGE);

  // Generate pages 2..N (page 1 is handled by index.astro)
  return Array.from({ length: totalPages - 1 }, (_, i) => ({
    params: { page: String(i + 2) },
    props: { currentPage: i + 2 },
  }));
}

const POSTS_PER_PAGE = 12;
const { currentPage } = Astro.props;

const allPosts = await getCollection('blog');
const sortedPosts = allPosts.sort(
  (a, b) => new Date(b.data.publishedAt).getTime() - new Date(a.data.publishedAt).getTime()
);

const totalPages = Math.ceil(sortedPosts.length / POSTS_PER_PAGE);
const startIndex = (currentPage - 1) * POSTS_PER_PAGE;
const paginatedPosts = sortedPosts.slice(startIndex, startIndex + POSTS_PER_PAGE);



{currentPage > 1 && (
  /blog/${currentPage - 1}/}>Previous

)}
{Array.from({ length: totalPages }, (_, i) => i + 1).map((page) => (
  
    href={page === 1 ? '/blog/' : /blog/${page}/}

    class:list={[{ active: page === currentPage }]}
  >
    {page}
  
))}
{currentPage < totalPages && (
  /blog/${currentPage + 1}/}>Next

)}
`


Why not paginate(): The built-in paginate() function generates URLs like /blog/1/, /blog/2/. We want /blog/ for page 1 and /blog/2/ for subsequent pages. Manual pagination with index.astro + [page].astro gives cleaner URLs.



9. Astro Config

astro.config.mjs


`js

// @ts-check
import { defineConfig } from 'astro/config';
import tailwindcss from '@tailwindcss/vite';
import sitemap from '@astrojs/sitemap';
import robotsTxt from 'astro-robots-txt';
import compress from 'astro-compress';
import expressiveCode from 'astro-expressive-code';
import pagefind from 'astro-pagefind';
import icon from 'astro-icon';
import rehypeSlug from 'rehype-slug';
import rehypeAutolinkHeadings from 'rehype-autolink-headings';
import rehypeExternalLinks from 'rehype-external-links';
import { remarkReadingTime } from './src/plugins/remark-reading-time.mjs';

export default defineConfig({
  site: 'https://yoursite.com',  // Required for sitemap + canonical URLs

  vite: {
    plugins: [tailwindcss()],
  },

  integrations: [
    expressiveCode({
      themes: ['github-dark-default'],
      styleOverrides: {
        borderRadius: '0',
        borderColor: 'var(--color-border)',
      },
    }),
    sitemap(),
    robotsTxt(),
    icon(),
    pagefind(),
    compress(),  // MUST be last — runs after all other transforms
  ],

  markdown: {
    rehypePlugins: [
      rehypeSlug,
      [rehypeAutolinkHeadings, {
        behavior: 'wrap',
        properties: { class: 'heading-anchor' },
      }],
      [rehypeExternalLinks, {
        target: '_blank',
        rel: ['noopener', 'noreferrer'],
      }],
    ],
    remarkPlugins: [remarkReadingTime],
  },
});
`


Remark reading time plugin — src/plugins/remark-reading-time.mjs


`js

import { toString } from 'mdast-util-to-string';

export function remarkReadingTime() {
  return function (tree, { data }) {
    const textOnPage = toString(tree);
    const readingTime = Math.ceil(textOnPage.split(/\s+/).length / 230);
    data.astro.frontmatter.readingTime = readingTime;
  };
}
`


Integration order matters:
expressiveCode — must come before sitemap (it processes code blocks during build)

sitemap / robotsTxt / icon / pagefind — order doesn't matter

compress — MUST be last (it compresses all output after other integrations finish)




10. TypeScript Config

tsconfig.json


`json

{
  "extends": "astro/tsconfigs/strict",
  "include": [".astro/types.d.ts", "**/*"],
  "exclude": ["dist"]
}
`


Notes:
astro/tsconfigs/strict enables strict mode + path aliases

.astro/types.d.ts is auto-generated by astro sync — provides types for content collections

Run npx astro sync after changing content.config.ts to regenerate types




11. Project Structure

`

my-site/
  astro.config.mjs
  package.json
  tsconfig.json
  public/
    favicon.ico
    favicon.png
    images/
      brand/
        og-default.png      # 1200x630 OG image
      clients/               # Client logos
    _redirects               # Cloudflare Pages redirects
    robots.txt               # (auto-generated by astro-robots-txt)
  src/
    content.config.ts        # Collection definitions + Zod schemas
    content/
      blog/
        *.md                 # Blog posts
      cases/
        *.md                 # Case studies
      services/
        *.md                 # Service pages
    components/
      Nav.astro
      Footer.astro
      SEO.astro
    data/
      site-config.ts         # Centralized site URL, CTA text, etc.
      service-mapping.ts     # Tag-to-service mapping for related services
    layouts/
      BaseLayout.astro
      BlogLayout.astro
      CaseStudyLayout.astro
    pages/
      index.astro
      about.astro
      contact-us.astro
      privacy.astro
      terms.astro
      404.astro
      blog/
        index.astro          # Blog listing page 1
        [page].astro         # Blog listing pages 2..N
        [...slug].astro      # Individual blog posts
      case-studies/
        index.astro
        [...slug].astro
      services/
        index.astro
        [...slug].astro
    plugins/
      remark-reading-time.mjs
    styles/
      global.css             # Tailwind v4 @theme tokens + prose + utilities
  functions/                 # Cloudflare Pages Functions (serverless)
    api/
      contact.ts
  dist/                      # Build output (git-ignored)
`




Production Tips

Font loading: Preload variable font .woff2 files and define @font-face with font-display: swap in your BaseLayout. Do not rely solely on CSS @import url() for fonts — it causes render-blocking.


Image zoom: Use medium-zoom for prose images. Import it in a

Table of Contents

1. Project Initialization

2. Tailwind v4 Integration

3. Content Collections

src/content.config.ts

Content file structure

Frontmatter example (blog)

Key patterns

4. Layout Hierarchy

BaseLayout — src/layouts/BaseLayout.astro

`BaseLayout —` src/layouts/BaseLayout.astro