documenting-stack

# 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 ```markdown --- 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.** ```bash # Check META for stack's packageJson grep -A 30 "'stackname'" apps/cli/src/__meta__.ts # Check what libraries support this stack grep -B 2 -A 5 "stacks:.*'stackname'" apps/cli/src/__meta__.ts # Also check for stacks: 'all' (available to every stack) grep -A 2 "stacks: 'all'" apps/cli/src/__meta__.ts ``` ### Step 2: Analyze Template Files ```bash # Find all template files for stack ls -la apps/cli/templates/stack/{stackname}/ # Check library templates ls -la apps/cli/templates/libraries/ # Verify specific files mentioned in docs find apps/cli/templates -name "filename.hbs" # Check for frontmatter (only/mono filters) 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 name - `description`: Keep original style - framework presentation (DON'T change) **Document structure:** 1. Brief explicit description (what you get as result) 2. Link to official docs (MANDATORY, `→` syntax) 3. "What create-faster adds" section 4. "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:** ```bash # Verify scripts exist in META grep "scripts:" -A 10 apps/cli/src/__meta__.ts | grep stackname # Verify dependencies exist in META grep "dependencies:" -A 10 apps/cli/src/__meta__.ts | grep stackname # Verify template files exist ls apps/cli/templates/stack/{stackname}/ # Verify library compatibility 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:** - [ ] `title:` in YAML (don't add `# Title` after) - [ ] `description:` keeps original framework presentation style **Document:** - [ ] `## Presentation` section added after frontmatter - [ ] Brief explicit description (what you get as result) - [ ] Link to official documentation (→ syntax, MANDATORY) - [ ] "What create-faster adds" section - [ ] NO framework-agnostic options (Biome, git, etc.) - [ ] NO optional features claimed as defaults - [ ] NO standard configs everyone uses - [ ] "Compatible Modules" section with links to standalone module pages - [ ] NO inline module documentation (modules live in `modules/{category}/`) - [ ] Technical changes focus on OUR additions - [ ] Turborepo differences noted where applicable - [ ] Integration notes for ORM/database **Verification (MANDATORY):** - [ ] Every script verified in `META.stacks[name].packageJson.scripts` - [ ] Every dependency verified in `META.stacks[name].packageJson.dependencies` - [ ] Every file reference verified in `apps/cli/templates/` - [ ] Library compatibility verified in `META.libraries[name].support` - [ ] Env vars verified in META `envs` fields (if documented) - [ ] Frontmatter filters checked (e.g., `only: mono` means turborepo-only)