astro-strapi-starter

Astro x Strapi Starter AI-native first — agent context (AGENTS.md), Agent Skills under .ai/, and Cursor rules are part of the product, not a README afterthought. You extend the stack with AI, not against it. 🔗 Live Demo

All-in-one starter combining Astro, Strapi CMS, TailwindCSS, and shadcn/ui with support for Strapi Astro Loader and Strapi Astro Blocks Field. Details: AI-native support.

---

✨ Features

• ⚡ Astro 7 - Latest version with ultra-fast static sites
• 📝 Strapi CMS - Headless CMS for content management
• 🧱 Strapi Astro Blocks Field - Modular & flexible content block system
• 🔄 Strapi Astro Loader - Automatic content loading from Strapi
• 🤖 AI-native support - AGENTS.md, Agent Skills under .ai/, and Cursor rules tailored to Astro x Strapi for Loader & Blocks
• 🎨 TailwindCSS 4 - Modern utility-first CSS styling
• 🧩 shadcn/ui - Pre-configured React component library (optional)
• 🌗 Dark / Light mode - Toggle with system preference detection
• 🔀 Tailwind / shadcn toggle - Live component showcase comparing both approaches
• 🔤 Inter font - Self-hosted variable font via @fontsource
• 📱 Responsive Design - Optimized for all devices
• 🌐 TypeScript - Full type support

---

📖 Table of Contents

• ✨ Features
• 🚀 Quick Start
• 🗂️ Project Structure
• 🤖 AI-native support
• 🏆 Lighthouse Score
• 🌗 Dark / Light Mode
• 🧩 UI Components: shadcn/ui vs Pure Tailwind
• 📦 Strapi Astro Packages
• 🔨 Available Commands
• 🌍 Deploy
• 📚 Useful Links
• 🔧 Development
• 🤝 Contributing
• 📄 License

---

🚀 Quick Start

1. Use a starter template

# NPM
npm create astro@latest -- --template VirtusLab-Open-Source/astro-strapi-starter

# Yarn
yarn create astro --template VirtusLab-Open-Source/astro-strapi-starter

2. Environment Variables Setup

Create a .env file in the root directory:

# Strapi Configuration
STRAPI_URL=http://localhost:1337
STRAPI_TOKEN=your_strapi_api_token_here

3. Run the Project

npm run dev

Open http://localhost:4321 in your browser.

🗂️ Project Structure

/
├── src/
│   ├── components/
│   │   ├── blocks/                # Strapi block components (Astro + Tailwind)
│   │   │   ├── BlockRenderer.astro
│   │   │   ├── TextBlock.astro
│   │   │   ├── QuoteBlock.astro
│   │   │   ├── MediaBlock.astro
│   │   │   ├── CTABlock.astro
│   │   │   └── HeroBlock.astro
│   │   ├── tailwind/              # Pure Tailwind Astro components
│   │   │   ├── Button.astro
│   │   │   ├── Card.astro
│   │   │   ├── CardHeader.astro
│   │   │   ├── CardTitle.astro
│   │   │   ├── CardDescription.astro
│   │   │   ├── CardContent.astro
│   │   │   └── Badge.astro
│   │   ├── ui/                    # shadcn/ui React components
│   │   │   ├── button.tsx
│   │   │   ├── card.tsx
│   │   │   ├── badge.tsx
│   │   │   └── separator.tsx
│   │   ├── showcase/              # Side-by-side component demos
│   │   │   ├── TailwindShowcase.astro
│   │   │   └── ShadcnShowcase.tsx
│   │   ├── Toolbar.astro          # Sticky header with logo + toggles
│   │   ├── ThemeToggle.astro      # Dark / Light mode switch
│   │   └── UIToggle.astro         # Tailwind / shadcn switch
│   ├── lib/
│   │   └── utils.ts               # cn() utility for class merging
│   ├── pages/
│   │   └── index.astro            # Homepage
│   ├── types/
│   │   └── strapi/                # Strapi TS types (`index.ts` re-exports modules)
│   ├── content.config.ts          # Strapi Loader configuration
│   ├── styles/
│   │   └── global.css             # Theme, fonts, toggle visibility rules
│   └── utils/
│       └── media.ts               # Strapi Media utils
├── components.json                # shadcn/ui configuration
├── package.json
└── astro.config.mjs

🤖 AI-native support

This starter ships first-class agent context for any AI coding tool (Cursor, Claude Code, Copilot, and other SKILL.md–compatible clients):

• AGENTS.md (root) points to the full guide: .ai/AGENTS.md
• Agent Skills (YAML + markdown) under .ai/:
  • .ai/astro-strapi-starter/SKILL.md — end-to-end workflow for this template (the only long-form skill kept here)
  • .ai/astro-strapi-loader/SKILL.md and .ai/astro-strapi-blocks/SKILL.md — short stubs with links to the canonical SKILL (and related) files in astro-strapi-loader and astro-strapi-blocks (no duplicate prose in this repo)
• Cursor project rules in .cursor/rules/ — astro-strapi-loader and astro-strapi-blocks are thin pointers to the loader and blocks upstream rules; astro-strapi-starter and tailwind-shadcn are defined in this repo

The authoritative manuals for the packa