Adding Stacks to create-faster

Overview

Add new framework stacks (Next.js, Expo, Remix, Astro, etc.) to the create-faster CLI scaffolding tool with complete, functional templates.

Core principle: Understand-first, copy-second. Create a working reference project BEFORE writing templates.

When to Use

Use this skill when:

• Adding a new app stack (Next.js, Remix, Astro, SvelteKit, etc.)
• Adding a new server stack (Hono, Express, Fastify, etc.)
• The framework is new to the create-faster tool

Do NOT use for:

• Fixing existing templates (use fixing-templates skill)
• Updating dependencies (use updating-dependencies skill)
• Adding modules to existing stacks

The Systematic Process

digraph adding_stack {
    "Start" [shape=doublecircle];
    "Create reference project" [shape=box];
    "Understand structure" [shape=box];
    "Identify all dependencies" [shape=box];
    "Create templates" [shape=box];
    "Test generation" [shape=box];
    "Verify functional?" [shape=diamond];
    "Fix issues" [shape=box];
    "Add to META" [shape=box];
    "Done" [shape=doublecircle];

    "Start" -> "Create reference project";
    "Create reference project" -> "Understand structure";
    "Understand structure" -> "Identify all dependencies";
    "Identify all dependencies" -> "Create templates";
    "Create templates" -> "Test generation";
    "Test generation" -> "Verify functional?";
    "Verify functional?" -> "Add to META" [label="yes"];
    "Verify functional?" -> "Fix issues" [label="no"];
    "Fix issues" -> "Test generation";
    "Add to META" -> "Done";
}

Step 1: Create Reference Project FIRST

DO NOT skip this step. DO NOT assume you know the structure.

1. Create temporary project with official CLI/starter:

   cd /tmp
   npm create [framework]@latest temp-[framework]
   # Follow prompts, select typical options
   

2. Inspect complete structure:

   tree -L 3 -I 'node_modules' temp-[framework]/
   

3. Read ALL critical files:

   • package.json (all dependencies & scripts)
   • Config files (vite.config, next.config, etc.)
   • Entry points (main.tsx, app.tsx, etc.)
   • Routing structure

Why this matters: Without reference project, you WILL miss dependencies, configs, and source files.

Step 2: Understand Stack Architecture

Research the framework's unique characteristics:

1. Build system: Vite? Webpack? Custom?
2. Routing: File-based? Config-based? Library?
3. Server rendering: SSR? SSG? Hybrid?
4. Entry points: Where does code start?
5. Config files: What's required vs optional?

Check official docs:

• Getting Started guide
• Project Structure docs
• Configuration reference

DO NOT assume similarity to other frameworks. Each has unique patterns.

Step 3: Identify ALL Dependencies

Create comprehensive dependency checklist from reference project:

Core Dependencies:

• [ ] Framework runtime packages
• [ ] Router library (if separate)
• [ ] Build tool (vite, webpack, etc.)
• [ ] Server runtime (if needed)

Dev Dependencies:

• [ ] TypeScript types
• [ ] Build plugins
• [ ] Dev tools
• [ ] Linters/formatters (if included by default)

Common Mistakes:

• Missing build plugins (critical!)
• Wrong package versions
• Missing peer dependencies
• Incorrect package names

Verification: Compare your list to reference package.json line-by-line.

CRITICAL: Copy version numbers EXACTLY as they appear in reference project. Do NOT:

• "Improve" to latest versions
• Guess at version numbers
• Use different versions across related packages
• Example: If reference has ^1.132.0, use ^1.132.0 NOT ^1.134.13

Step 4: Create Template Structure

Map reference project to create-faster structure:

templates/stack/[stackname]/
  package.json.hbs          # Dependencies + scripts
  [config].config.ts.hbs    # Vite, Next, etc.
  tsconfig.json.hbs         # TypeScript config
  src/                      # Source code structure
    [entry-point].tsx.hbs   # Main entry
    routes/                 # Routing (if file-based)
      __root.tsx.hbs
      index.tsx.hbs
    components/             # Shared components
  public/                   # Static assets (if needed)

For each template file:

1. Add magic comments if needed:

   {{!-- @repo:turborepo --}}
   {{!-- @scope:app --}}
   

2. Add Handlebars conditionals:

   {{#if (eq repo "turborepo")}}
   "@repo/config": "*",
   {{/if}}
   

3. Handle ORM/database integration:

   {{#if (eq orm "drizzle")}}
   "drizzle-orm": "^0.38.3",
   {{/if}}
   

Copy working code from reference project, adapt with Handlebars.

Step 5: Test Template Generation

DO NOT assume templates work. Verify.

1. Test generation in single repo mode:

   cd /tmp
   bun create-faster test-single --stack [stackname]
   

2. Verify generated files:

   tree test-single/
   cat test-single/package.json
   

3. Test build works:

   cd test-single
   bun install
   bun run dev  # Should start without errors
   

4. Test in turborepo mode:

   cd /tmp
   bun create-faster test-turbo \
     --app web:[stackname] \
     --app api:hono
   

If ANY errors: Fix templates, regenerate, re-test. Repeat until clean.

Step 6: Add to META

Only after templates are verified working:

// apps/cli/src/__meta__.ts
META.stacks['stackname'] = {
  type: 'app' | 'server',
  scope: 'app',
  label: 'Framework Name',
  hint: 'Short description',
  modules: {
    'Category Name': {
      'module-id': {
        label: 'Module Label',
        hint: 'What it does',
        packageName: 'optional-package-name',
      },
    },
  },
}

Choosing modules:

• Research popular ecosystem libraries
• Check community templates for common patterns
• Add 2-5 essential modules (not all possible)
• Can expand later

Step 7: Test with Modules

If you added modules, test them:

1. Generate with module enabled:

   bun create-faster test-module \
     --stack [stackname]:[module-id]
   

2. Verify module templates rendered correctly

3. Test build with module active

Checklist - All Steps Required

Before considering task complete:

• [ ] Created reference project with official CLI
• [ ] Inspected all files (package.json, configs, source)
• [ ] Understood framework-specific patterns
• [ ] Created complete template structure (not just configs)
• [ ] Added ALL dependencies from reference
• [ ] Added ALL config files from reference
• [ ] Created source file templates (entry, routes, components)
• [ ] Tested generation in single repo mode
• [ ] Tested generation in turborepo mode
• [ ] Verified dev server starts
• [ ] Verified build completes
• [ ] Added to meta.ts with appropriate modules
• [ ] Tested module generation (if modules added)

Special Filename Handling

create-faster naming conventions:

• __filename → .filename (for dotfiles like .gitignore, .env)
• To create files that literally start with __, use triple underscore:
  • ___root.tsx.hbs → __root.tsx ✅
  • __root.tsx.hbs → .root.tsx ❌

Examples:

• TanStack Start: ___root.tsx.hbs (needs literal __root.tsx)
• Next.js App Router: No issue (uses app/ directory, not __ files)

Common Rationalizations - STOP

| Excuse | Reality | |--------|---------| | "I'll copy Next.js and adapt" | Each framework is unique. You WILL miss things. | | "Config files are enough" | Without source files, nothing runs. | | "I know this framework" | Create reference anyway. Starters evolve. | | "I'll add source later" | Templates must be complete NOW. | | "Close enough, it'll probably work" | Probably = definitely broken. Test it. | | "Just package.json for now" | Incomplete = non-functional. Do it right. | | "I can skip testing" | Untested templates = broken templates. | | "Vinxi and Vite are the same" | Assumptions like this cause failures. Verify. | | "Triple underscore? That's weird" | Naming edge case from testing. Use it or file breaks. |

Red Flags - You're About to Fail

STOP immediately if you think:

• "I'll just look at [other stack] first"
• "Config files should be enough to start"
• "I can add [critical part] later"
• "It's probably similar to [other framework]"
• "I don't need to test, it should work"

These thoughts = baseline failure pattern. Follow the process.

Quick Reference - File Checklist

Minimum required files:

• ✅ package.json.hbs (complete dependencies)
• ✅ Config file(s) (vite.config, next.config, etc.)
• ✅ tsconfig.json.hbs
• ✅ Entry point (main.tsx, app.tsx, etc.)
• ✅ At least one route/page
• ✅ Basic component structure (if framework uses components)
• ✅ public/ directory (if framework needs it)

If ANY missing: Templates incomplete. Keep working.

Real-World Impact

Without this skill (baseline):

• 20 minutes → broken templates
• Missing 10+ dependencies
• Zero source files
• Would not run at all

With this skill:

• 30-40 minutes → functional templates
• All dependencies present
• Complete source structure
• Verified working build

Extra 10-20 minutes = difference between broken and working.

Example: Adding TanStack Start

Reference the baseline test in /tmp/baseline-adding-tanstack-start.md to see all the mistakes this skill prevents.