adding-templates

# Adding Templates to create-faster ## Overview Add new content to the create-faster CLI: framework stacks, per-app libraries, or project-level addons. All additions are data-driven through META configuration + Handlebars templates. **Core principle:** Understand-first, copy-second. Know the library/framework BEFORE writing templates. ## When to Use Use this skill when: - Adding a new framework stack (Remix, Astro, SvelteKit, etc.) - Adding a new library (tRPC, i18n, Storybook, etc.) - Adding a new project addon (new database, ORM, tooling) Do NOT use for: - Fixing existing templates (use `fixing-templates` skill) - Extracting a library from an external project (use `extracting-templates` skill first, then come here) - Updating dependency versions ## Architecture Context Adding content is **data-driven**. Most CLI code operates generically on META configuration. Only source files that define types need changes. Everything else is META entries + template files. **What does NOT change** when adding content (17+ files are generic): - `cli.ts`, `flags.ts`, `index.ts` — iterate META entries - `template-resolver.ts` — scans template directories by convention - `package-json-generator.ts` — merges from `META.*.packageJson` - `env-generator.ts` — collects envs from META - `handlebars.ts` — generic helpers - `addon-utils.ts` — generic compatibility checks - All prompts, TUI, summary code ### Three Addon Types | Type | META location | Template directory | Scope | |------|--------------|-------------------|-------| | Stack | `META.stacks` | `templates/stack/{name}/` | Per-app | | Library | `META.libraries` | `templates/libraries/{name}/` | Per-app | | Project addon | `META.project.{category}.options` | `templates/project/{category}/{name}/` | Project-level | ## Adding a Stack ### Source Changes **Only 2-3 source files need code changes:** #### a. Add to `StackName` union (`types/meta.ts`) ```typescript export type StackName = 'nextjs' | 'expo' | 'hono' | 'tanstack-start' | 'newstack'; ``` All downstream types derive from `StackName` automatically. #### b. Add stack entry to META (`__meta__.ts`) ```typescript newstack: { type: 'app' | 'server', label: 'Framework Name', hint: 'Short description', packageJson: { dependencies: { 'framework-core': '^1.0.0' }, devDependencies: { typescript: '^5' }, scripts: { dev: 'framework dev --port {{port}}', build: 'framework build', start: 'framework start --port {{port}}', }, }, }, ``` **Scripts with `{{port}}`:** `package-json-generator.ts` resolves placeholders: - Turborepo: `{{port}}` → `3000 + appIndex` - Single repo: the `--port {{port}}` portion is stripped entirely #### c. Add file extensions to KNOWN_EXTENSIONS (if needed, `lib/frontmatter.ts`) Non-standard extensions (`.svelte`, `.vue`, `.astro`) prevent the stack suffix parser from misidentifying them. ### Template Structure ``` templates/stack/{stackname}/ {config}.config.ts.hbs # Vite, Next, etc. tsconfig.json.hbs # TypeScript config src/ {entry-point}.tsx.hbs # Main entry routes/ # Routing (if file-based) components/ # Shared components public/ # Static assets (if needed) ``` ### Library Compatibility Check existing libraries with `support: { stacks: 'all' }`. React libraries shouldn't be available for non-React stacks — change to explicit list: ```typescript support: { stacks: ['nextjs', 'tanstack-start'] }, // React-only ``` ## Adding a Library ### META Entry (`META.libraries`) ```typescript newlib: { label: 'Library Name', hint: 'Short description', category: 'UI', // Groups in interactive prompt (UI, Content, Auth, API, Data Fetching, Forms, Deploy) support: { stacks: ['nextjs', 'tanstack-start'] }, // Optional: require other addons require: { orm: ['drizzle', 'prisma'] }, // Optional: turborepo shared package mono: { scope: 'pkg', name: 'libname' }, packageJson: { dependencies: { 'the-lib': '^1.0.0' }, // Optional: package exports (for shared packages) exports: { '.': './src/index.ts' }, }, // Optional: environment variables envs: [ { value: 'LIB_SECRET=changeme', monoScope: [{ pkg: 'libname' }, 'app'] }, ], }, ``` **Key fields:** - `category` — prompt group name (UI, Content, Auth, API, Data Fetching, Forms, Deploy) - `support.stacks` — which stacks can use this library (`'all'` or explicit list) - `require` — dependencies on other addons (e.g., better-auth requires orm) - `mono` — if set, library gets its own `packages/{name}/` in turborepo - `envs` — env vars with scope resolution (which `.env.example` files get them) ### Template Structure ``` templates/libraries/{libname}/ src/lib/{feature}.ts.hbs # Library setup files src/lib/{feature}-client.ts.hbs # Client-side setup src/app/api/{route}/route.ts.nextjs.hbs # Stack-specific API routes ``` ### Handlebars Conditionals for Cross-Library Integration When a library's behavior changes based on OTHER selected libraries: ```handlebars {{!-- In the library's own template --}} {{#if (hasLibrary "other-lib")}} import { something } from '{{#if (isMono)}}@repo/other{{else}}@/lib/other{{/if}}'; {{/if}} {{!-- Conditional feature based on project addon --}} {{#if (has "orm" "drizzle")}} import { db } from '{{#if (isMono)}}@repo/db{{else}}@/lib/db{{/if}}'; {{/if}} ``` ### Modifying Existing Templates Libraries often need to modify existing stack templates (e.g., `app-providers.tsx.hbs`): ```handlebars {{!-- Add import --}} {{#if (hasLibrary "newlib")}} import { NewLibProvider } from '@/lib/newlib'; {{/if}} {{!-- Add provider wrapper --}} {{#if (hasLibrary "newlib")}} <NewLibProvider> {{/if}} {children} {{#if (hasLibrary "newlib")}} </NewLibProvider> {{/if}} ``` **Wrap order matters** — check existing conditionals and add in the right position. ## Adding a Project Addon ### META Entry (`META.project.{category}.options`) ```typescript // In META.project.{category}.options: newoption: { label: 'Option Name', hint: 'Short description', mono: { scope: 'root' }, // or { scope: 'pkg', name: 'pkgname' } packageJson: { dependencies: { 'the-pkg': '^1.0.0' }, scripts: { 'task:run': 'the-pkg run' }, }, envs: [ { value: 'DB_URL="connection-string"', monoScope: [{ pkg: 'db' }, 'app'] }, ], }, ``` ### Template Structure ``` templates/project/{category}/{name}/ config-file.ts.hbs scripts/seed.ts.hbs ``` ## Programmatic Files — NO Templates **package.json** — generated from META `packageJson`. No `package.json.hbs`. **.env.example** — generated from META `envs`. No `.env.example.hbs`. ## Template Authoring Reference ### YAML Frontmatter ```yaml --- path: src/lib/feature.ts # Output path (single repo) mono: scope: app | pkg | root # Monorepo scope (overrides META) path: src/feature.ts # Monorepo path (relative to scope) only: mono | single | no-blueprint # Repo type filter deploymentPath: # Output path override keyed by deployment cloudflare: src/middleware.ts deploymentSkip: [cloudflare-static] # Deployments that do not get this file blueprintSkip: [org-dashboard-nextjs] # Blueprints that do not get this file --- ``` `TemplateFrontmatter` in `apps/cli/src/types/meta.ts` lists the keys; `AGENTS.md` > Declarative choice logic describes each one. ### Stack-Specific File Suffix `file.ext.{stack}.hbs` — only included when app uses that stack: ``` route.ts.nextjs.hbs → only for Next.js apps adapter.ts.hono.hbs → only for Hono apps ``` ### Available Handlebars Helpers `apps/cli/src/lib/handlebars.ts` (`registerHelpers`) is the source of truth; `AGENTS.md` describes each helper. | Helper | Purpose | |--------|---------| | `isMono` | Check if turborepo | | `hasLibrary "name"` | Check if current app has library (any app outside an app-scoped file) | | `has "category" "value"` | Check database/orm/deployment/linter/tooling selection, or `has "stack" "x"` for any app on the stack | | `databaseBinding "name"` | Check if the selected database declares `serverlessBinding: name` in META | | `hasContext "key"` | Check if key exists in context | | `hasRootScript "name"` | Check if the generated root `package.json` defines the script | | `appPort appName` | Get port for app (3000 + index) | | `camelCase str` | Convert a kebab or snake case string to camelCase | | `pascalCase str` | Convert a kebab or snake case string to PascalCase (`DATABASE_URL` is `DatabaseUrl`) | | `raw` | Block: renders its body as is | | `eq`, `ne`, `and`, `or` | Logical operators | ### Shared Blocks (Partials) When several templates must render the same block (a wrangler binding, a client options object, a host, a stack mapping), put it once in `templates/partials/{group}/{name}.hbs` and insert it with `{{> group/name}}`. Never copy the block. - The partial renders with the caller's context (helpers keep working); pass per-call values as hash parameters: `{{> posthog/client-options debug="import.meta.env.DEV"}}`. - By default it is called alone on its line, indented to the call, and ends with one line break. A partial called mid-line sets `inline: true` in its frontmatter and is inserted without a final line break. Registration normalizes the ending, so the file's final newline does not matter. - `setupTemplateEngine()` registers helpers and partials; partials are never generated as files. Details: `AGENTS.md`, Template system > Partials. ### Special Filename Handling - `__filename` → `.filename` (dotfiles like `.gitignore`) - `___filename` → `__filename` (literal double underscore) ## Testing **DO NOT assume templates work. Verify.** 1. Single repo mode: ```bash bunx create-faster test-single --app test-single:{stack}:{lib1},{lib2} ``` 2. Turborepo mode: ```bash bunx create-faster test-turbo --app web:{stack}:{lib1},{lib2} --app api:hono ``` 3. Verify: - All template files present in output - `package.json` has correct dependencies - Conditional code renders correctly for all combinations - `bun install && bun run dev` works 4. Test all library combinations that affect templates: - Library alone - Library + each cross-library integration - Library in single vs turborepo mode ## Checklist ### Stack - [ ] Added to `StackName` union in `types/meta.ts` - [ ] Added META entry with `packageJson` (deps + scripts) - [ ] Added file extension to `KNOWN_EXTENSIONS` (if applicable) - [ ] Created `templates/stack/{name}/` with all source files - [ ] Checked library compatibility (`stacks: 'all'` audit) - [ ] Tested single + turborepo mode - [ ] Verified dev/build works ### Library - [ ] Added META entry in `META.libraries` with category/support/require/mono/packageJson/envs - [ ] Created `templates/libraries/{name}/` with template files - [ ] Modified existing stack templates for cross-library conditionals - [ ] Used stack-specific suffix where needed (`.nextjs.hbs`) - [ ] Tested all library combinations