| name | documenting-stack |
| description | Use when documenting stacks, databases, or ORMs in create-faster MDX docs - focuses on technical changes and what we add beyond official setup |
Documenting Stack
Overview
Document what create-faster adds beyond official framework setup. Focus on technical changes, not framework features.
Core principle: Document OUR additions, link to THEIR docs.
When to Use
Use when:
- Adding new stack documentation (Next.js, Expo, TanStack Start, Hono)
- Documenting database/ORM integration (Drizzle, Prisma, PostgreSQL, MySQL)
- Updating existing stack docs after template changes
Do NOT use for:
- Project-specific documentation
- General framework tutorials (link to official docs)
- Module documentation (separate workflow)
Architecture Context
Where things live:
- Stack templates:
templates/stack/{framework}/
- Library templates:
templates/libraries/{library}/
- Project addon templates:
templates/project/{category}/{name}/
- Dependencies/scripts:
META.stacks[name].packageJson in __meta__.ts (NOT in templates)
- Env vars:
META.libraries[name].envs and META.project.*.options.*.envs (NOT in templates)
- Library compatibility:
META.libraries[name].support.stacks
- Documentation site:
apps/www/content/docs/
Package.json is programmatic. Scripts and dependencies are declared in META, not in template files. To verify what a stack provides, check META.stacks[name].packageJson in __meta__.ts.
Env vars are programmatic. Check envs fields in META addons, not template files.
Structure Template
---
title: Stack Name
description: Keep original style - framework presentation (don't change)
---
## Presentation
Brief explicit description of what you get as result (Full-stack X framework...).
[→ Official Documentation](https://...)
## What create-faster adds
Beyond the official setup, we include:
**Project Structure:**
- Pre-configured error pages
- Custom utilities directory
- Optimized layouts
**Development Scripts:**
- Custom scripts with purpose (build:analyze - Bundle analysis)
- Debug helpers (start:inspect - Node inspector)
**DO NOT include:**
- Framework-agnostic options (Biome, git, etc.)
- Default framework features (TypeScript, build tools)
- Optional features as if they're default
## Compatible Modules
List modules available for this stack with links to their standalone pages.
→ [shadcn/ui](/docs/modules/ui/shadcn) · [Next Themes](/docs/modules/ui/next-themes) · ...
Module documentation lives in `modules/{category}/`. Do NOT document modules inline.
Documentation Workflow
Step 1: Analyze META for Dependencies and Scripts
CRITICAL: META is the source of truth for dependencies and scripts, not template files.
grep -A 30 "'stackname'" apps/cli/src/__meta__.ts
grep -B 2 -A 5 "stacks:.*'stackname'" apps/cli/src/__meta__.ts
grep -A 2 "stacks: 'all'" apps/cli/src/__meta__.ts
Step 2: Analyze Template Files
ls -la apps/cli/templates/stack/{stackname}/
ls -la apps/cli/templates/libraries/
find apps/cli/templates -name "filename.hbs"
grep -l '^---' apps/cli/templates/stack/{stackname}/*.hbs
head -5 apps/cli/templates/stack/{stackname}/*.hbs
Document EXACTLY what files we create/modify. Cross-reference every claim with actual template files AND META.
Step 3: Structure Document
Frontmatter (YAML):
title: Stack namedescription: Keep original style - framework presentation (DON'T change)
Document structure:
- Brief explicit description (what you get as result)
- Link to official docs (MANDATORY,
→ syntax)
- "What create-faster adds" section
- "Compatible Modules" section with links to standalone module pages
CRITICAL - Don't add # Title:
Title in frontmatter already renders as H1. Adding # Title creates duplicate.
For compatible modules:
Link to standalone module pages in modules/{category}/. Do NOT document modules inline on stack pages. Use documenting-module skill for module documentation.
Step 4: Focus on Technical Changes
DO document:
- Files we create (verifiable in
apps/cli/templates/)
- Files we modify (verifiable in templates with conditionals)
- Custom utilities (functions in template files)
- Scripts from META
packageJson.scripts (with their purpose)
- Dependencies from META
packageJson.dependencies
- Turborepo vs single repo differences (check frontmatter
only: mono filters)
- Env vars from META
envs fields (with scope resolution)
DON'T document:
- What the framework/module does (official docs)
- Generic "benefits" or "why use"
- Basic usage examples (they have tutorials)
- Framework-agnostic options (Biome, git - user chooses)
- Optional features as defaults
- Standard configs everyone uses (TypeScript strict)
- Dependencies not in META (verify!)
- Scripts not in META (verify!)
Step 5: Verify Every Claim
MANDATORY verification before publishing:
grep "scripts:" -A 10 apps/cli/src/__meta__.ts | grep stackname
grep "dependencies:" -A 10 apps/cli/src/__meta__.ts | grep stackname
ls apps/cli/templates/stack/{stackname}/
grep "'stackname'" apps/cli/src/__meta__.ts
Every script, dependency, and file reference MUST be verified against the codebase. Existing docs have had factual errors (wrong script commands, nonexistent dependencies).
RED FLAGS - You're Documenting Wrong
STOP if you write:
# Stack Name title (title in frontmatter already renders as H1)- Changed description style (keep original framework presentation)
- Inline module documentation (modules have their own pages)
- "Why use X?" explanations (that's official docs' job)
- Generic framework features (link to docs instead)
- Framework-agnostic options as stack features (Biome, git, etc.)
- Optional features presented as defaults
- Default framework configs everyone uses (TypeScript strict, etc.)
- Dependencies not verified in META (e.g., claiming
@hono/zod-validator when it's not in META)
- Scripts not verified in META (e.g., claiming
build script when only dev and start exist)
These mean: Refocus on what create-faster adds, not what the framework does. And VERIFY against code.
Common Mistakes
| Mistake | Fix |
|---|
| Documenting modules inline | Link to standalone module pages in modules/{category}/ |
| Explaining framework features | Link to official docs, focus on our additions |
| No file structure | Show tree with files created |
| Missing "What we add" | Required section at top |
| Verbose descriptions | Technical changes only |
| No official doc link | MANDATORY at top |
| Unverified dependencies | Check META.stacks[name].packageJson |
| Unverified scripts | Check META.stacks[name].packageJson.scripts |
| Checking package.json.hbs | Package.json is programmatic, check META instead |
Rationalization Table
| Excuse | Reality |
|---|
| "Need H1 title for clarity" | Frontmatter title renders as H1. Don't duplicate. |
| "Better description style" | Keep original framework presentation style. |
| "Should document modules here too" | Modules have their own pages. Link, don't duplicate. |
| "Need context about framework" | Official docs exist. Link to them. |
| "More detail is better" | Technical changes only. Avoid bloat. |
| "Should explain benefits" | Features = official docs. Our additions = us. |
| "Biome/git are part of stack" | Framework-agnostic options. Not stack-specific. |
| "I saw it in the old docs" | Old docs had errors. Verify against META and templates. |
| "The package.json template has it" | There IS no package.json template. It's programmatic from META. |
Template Checklist
Frontmatter:
Document:
Verification (MANDATORY):
