adding-stacks
Use when adding a new framework/stack to create-faster CLI tool - addresses copy-first mentality, incomplete implementations, and missing dependencies
When & Why to Use This Skill
This Claude skill provides a systematic, 'understand-first' workflow for adding new framework stacks to the create-faster CLI tool. It streamlines the creation of high-quality scaffolding templates for frameworks like Next.js, Remix, and Astro by ensuring complete dependency mapping, accurate configuration files, and verified source structures, effectively eliminating the common pitfalls of incomplete or broken CLI implementations.
Use Cases
- Case 1: Integrating new frontend frameworks (e.g., SvelteKit, TanStack Start) into a custom scaffolding tool with production-ready defaults.
- Case 2: Adding backend server stacks like Hono or Fastify while ensuring all peer dependencies and build-tool plugins are correctly identified from a reference project.
- Case 3: Automating the generation of complex Handlebars templates for monorepo (Turborepo) compatibility and conditional ORM integrations.
- Case 4: Establishing a rigorous testing and verification pipeline to ensure that every newly added stack produces a buildable and runnable project out of the box.
| name | adding-stacks |
|---|---|
| description | Use when adding a new framework/stack to create-faster CLI tool - addresses copy-first mentality, incomplete implementations, and missing dependencies |
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.
Create temporary project with official CLI/starter:
cd /tmp npm create [framework]@latest temp-[framework] # Follow prompts, select typical optionsInspect complete structure:
tree -L 3 -I 'node_modules' temp-[framework]/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:
- Build system: Vite? Webpack? Custom?
- Routing: File-based? Config-based? Library?
- Server rendering: SSR? SSG? Hybrid?
- Entry points: Where does code start?
- 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.0NOT^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:
Add magic comments if needed:
{{!-- @repo:turborepo --}} {{!-- @scope:app --}}Add Handlebars conditionals:
{{#if (eq repo "turborepo")}} "@repo/config": "*", {{/if}}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.
Test generation in single repo mode:
cd /tmp bun create-faster test-single --stack [stackname]Verify generated files:
tree test-single/ cat test-single/package.jsonTest build works:
cd test-single bun install bun run dev # Should start without errorsTest 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:
Generate with module enabled:
bun create-faster test-module \ --stack [stackname]:[module-id]Verify module templates rendered correctly
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.