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)

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

## Modules

### Module Name

*[→ Module Documentation](https://...)*

**Technical changes:**

Files added:
\`\`\`
src/
├── path/to/
│   └── file.tsx        # Description
└── config.json         # Description

# Turborepo only:
packages/name/
└── package.json        # Description
\`\`\`

**Modified files:**
- `file.tsx` - What changed and why

**Integration notes:**
- How it works with ORM/database/etc.
- Turborepo vs single repo differences

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)
Categorized module sections ("UI & Styling", "Data Fetching")
"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 (Turbopack is optional, not default)
Default framework configs everyone uses (TypeScript strict, etc.)
Module descriptions without technical changes
Bullet lists of dependencies without file structure

These mean: Refocus on what create-faster adds, not what the framework does.

Documentation Workflow

Step 1: Analyze Templates

CRITICAL: Templates are the source of truth. Verify every file reference.

# Find all template files for stack
ls -la apps/cli/templates/stack/{stackname}/

# Check modules (not all stacks have modules directories)
ls -la apps/cli/templates/modules/{framework}/

# Verify specific files mentioned in docs
find apps/cli/templates -name "filename.hbs"

# Check package.json for scripts
grep "script-name" apps/cli/templates/stack/{stackname}/package.json.hbs

Document EXACTLY what files we create/modify. Cross-reference every claim with actual template files.

Step 2: Structure Document

Frontmatter (YAML):

title: Stack name
description: 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
Modules (flat list, no categories)

CRITICAL - Don't add # Title: Title in frontmatter already renders as H1. Adding # Title creates duplicate.

For each module:

Title (### Module Name)
Link to module docs
Technical changes (files added/modified)
Tree structure showing files
Integration notes if applicable

Step 3: Focus on Technical Changes

DO document:

Files we create (verifiable in apps/cli/templates/)
- Example: apps/cli/templates/modules/nextjs/shadcn/src/lib/utils.ts.hbs
- Example: apps/cli/templates/stack/nextjs/src/hooks/use-mobile.ts.hbs
Files we modify (verifiable in apps/cli/templates/)
- Example: apps/cli/templates/stack/nextjs/next.config.ts.hbs (MDX support)
Custom utilities (functions in template files)
- Example: cn() function in utils.ts
- Example: useIsMobile() hook in use-mobile.ts
Custom scripts with clear purpose (in package.json templates)
- Example: build:analyze in apps/cli/templates/stack/nextjs/package.json.hbs
- Example: start:inspect in apps/cli/templates/stack/nextjs/package.json.hbs
Turborepo package structure (conditional based on repo type)
Integration configs (ORM adapters, database providers)

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 (Turbopack is optional)
Standard configs everyone uses (TypeScript strict)

Step 4: Mini Configs Emphasis

Highlight create-faster value:

Pre-configured optimizations
Utilities you'd repeatedly create
Scripts that speed up dev workflow
Patterns to avoid repetition

Example:

**Development Scripts:**
- `build:analyze` - Bundle size analysis with @next/bundle-analyzer
- `start:inspect` - Debug mode with Node inspector

*Why these?* Common debugging/optimization tasks made one command.

Common Mistakes

| Mistake | Fix | |---------|-----| | Categorizing modules | Flat list with ### Module Name | | 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 |

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. | | "Categories help organization" | Flat structure is clearer, user can Ctrl+F | | "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. | | "Turbopack is default" | It's optional. Don't claim as default. | | "TypeScript strict is our addition" | Everyone uses strict. Not worth mentioning. | | "Tree structure is extra work" | Shows exactly what we create. Essential. | | "Integration notes aren't needed" | ORM/database combos need explanation. |

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
[ ] Modules section (flat, no categories like "UI & Styling")
[ ] Each module has link to official docs
[ ] Each module shows files added/modified with tree structure
[ ] Technical changes focus on OUR additions
[ ] Turborepo differences noted where applicable
[ ] Integration notes for ORM/database modules
[ ] No "Why use X?" sections
[ ] No framework feature explanations

Verification (MANDATORY):

[ ] Every file reference verified in apps/cli/templates/
[ ] Every script reference verified in package.json.hbs
[ ] Every utility function verified in template source
[ ] Error page references checked against actual templates
[ ] Module structure verified (some use inline conditionals, not separate files)

Real-World Impact

Without this skill:

20 minutes → Verbose doc mixing framework features + our additions
Categories make finding modules harder
Missing technical details about files created
No clarity on what create-faster actually adds

With this skill:

10 minutes → Clean doc focused on technical changes
Flat module list, easy to scan
Clear file structures showing our additions
Highlights mini configs and optimizations