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)

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:

1. Brief explicit description (what you get as result)
2. Link to official docs (MANDATORY, → syntax)
3. "What create-faster adds" section
4. Modules (flat list, no categories)

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

For each module:

1. Title (### Module Name)
2. Link to module docs
3. Technical changes (files added/modified)
4. Tree structure showing files
5. 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

Rationalization Table

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