Astro Content Layer Expert
Type-safe content management with loaders, Zod schemas, and the unified Content Layer API.
Agent Workflow (MANDATORY)
Before ANY implementation, use TeamCreate to spawn 3 agents:
- fuse-ai-pilot:explore-codebase - Check existing collections, loaders, and content structure
- fuse-ai-pilot:research-expert - Verify latest Content Layer docs via Context7/Exa
- mcp__context7__query-docs - Get loader and schema examples
After implementation, run fuse-ai-pilot:sniper for validation.
Overview
When to Use
- Managing blog posts, docs, or product descriptions in Markdown/MDX
- Fetching content from a CMS, API, or database with type safety
- Needing TypeScript autocomplete for frontmatter fields
- Migrating from Astro 4 legacy content collections
Why Content Layer API
| Feature | Benefit |
|---|---|
src/content.config.ts | Single config file at project root |
| Built-in loaders | glob() and file() for local files |
| Custom loaders | Fetch from any external source |
| Zod 4 schemas | Full TypeScript type safety |
astro sync | Generates types from collections |
Core Concepts
Config File Location
The config file moved from src/content/config.ts to src/content.config.ts in Astro 5+.
Collection Types
| Loader | Use Case |
|---|---|
glob() | Multiple files in a directory (MD, MDX, JSON, YAML) |
file() | Single JSON/YAML file with multiple entries |
| Custom | Remote API, database, or any async data source |
Key APIs
| API | Description |
|---|---|
getCollection(name) | Fetch all entries in a collection |
getEntry(name, id) | Fetch a single entry by ID |
render(entry) | Render a content entry to HTML + headings |
defineCollection() | Define a collection with loader and schema |
Reference Guide
| Need | Reference |
|---|---|
| Overview & concepts | overview.md |
| Config file setup | config.md |
| Glob, file, custom loaders | loaders.md |
| getCollection / getEntry | querying.md |
| render() + headings | rendering.md |
| MDX + Remark/Rehype | mdx.md |
| Blog collection example | templates/blog-collection.md |
| Custom remote loader | templates/custom-loader.md |
Best Practices
- Always define schemas — Never skip Zod validation
- Run
astro sync— After changingcontent.config.ts - Use
glob()for local files — Supports MD, MDX, JSON, YAML, TOML - Custom loaders for remote data — CMS, REST API, GraphQL
render()for MDX — ReturnsContentcomponent + headings array