Use when updating library or project addon versions in create-faster __meta__.ts, especially when the update may involve breaking changes, new packages, renamed APIs, or cross-integration impacts
Installer avec Codex ou Claude Copiez ce prompt, collez-le dans Codex, Claude ou un autre assistant, puis laissez-le vérifier la page du skill et l'installer pour vous.
Une commande directe contourne le prompt de vérification. Examinez la source avant de l'exécuter.
Use when updating library or project addon versions in create-faster __meta__.ts, especially when the update may involve breaking changes, new packages, renamed APIs, or cross-integration impacts
Updating Libraries in create-faster
Overview
Safely update library and project addon versions, catching breaking changes before they reach generated projects.
Core principle: Research first, inventory second, change third, verify fourth. Never change a version without understanding its full blast radius.
When to Use
Use this skill when:
Bumping a version in META.libraries or META.project options
A library has released a new major/minor with breaking changes
Adapters, plugins, or integrations have been restructured
Updating stack frameworks (Next.js, Expo, Hono) — different surface area
Scope: One library/addon per invocation. Atomic commits. If a cascading peer dependency bump is needed (e.g., updating library X requires bumping library Y), that's a separate invocation.
Phase 2 gates Phase 3 (no changes without complete inventory)
Tests gate generation in Phase 4 (no generation until bun test passes)
Generation gate commit in Phase 5 (no commit until generated projects build)
Phase 1 — Research
DO NOT skip this. DO NOT rely on assumptions about what changed.
The baseline failure pattern is: agent reads the user's description of breaking changes and starts modifying code immediately, making assumptions about backward compatibility without verification.
Step 1: Resolve the library with context7
Use context7 MCP: resolve-library-id for the library name
Then: query-docs for migration guide, changelog, breaking changes
If context7 doesn't have the library, move to Step 2 — web search is the fallback, not an excuse to skip research entirely.
Step 2: Fetch changelog/migration guide
Use WebFetch or WebSearch to find:
The library's GitHub releases page
Migration guide (if one exists)
Changelog entries between current and target version
At least one of Step 1 or Step 2 must produce concrete findings. If neither yields results, state this explicitly and proceed with extra caution in Phase 4 (test more combinations, not fewer).
Step 3: Document findings
Produce a structured research summary:
Library: better-auth
Current: ^1.4.10
Target: ^1.5.3
Breaking changes:
- Adapters moved to separate packages (@better-auth/drizzle-adapter, @better-auth/prisma-adapter)
- Import path changed: 'better-auth/adapters/drizzle' → '@better-auth/drizzle-adapter'
New packages: @better-auth/drizzle-adapter, @better-auth/prisma-adapter
Removed packages: none (core package still exists)
Renamed APIs: none
New peer dependencies: none
New env vars: none
New configuration: none
DO NOT proceed to Phase 2 without this summary. If you can't find a changelog, state that explicitly and proceed with caution.
Phase 2 — Map Touchpoints
DO NOT change anything yet. Build the full inventory first.
The baseline failure pattern is: agent finds files by browsing around, misses cross-references, and starts editing before understanding the full picture.
4-category systematic search
Category 1: META entry
Read the library/addon entry in apps/cli/src/__meta__.ts. Document:
Version string
All dependencies (including $when conditionals)
Env vars
Exports
Require constraints
Mono scope
Support (which stacks)
Category 2: Direct templates
# For libraries:ls apps/cli/templates/libraries/{name}/
# For project addons:ls apps/cli/templates/project/{category}/{name}/
List every template file with its purpose.
Category 3: Cross-references (CRITICAL)
This is the most commonly missed category. Other templates conditionally reference your library:
# Search for Handlebars conditionals referencing this library
grep -rn 'hasLibrary "{name}"' apps/cli/templates/
grep -rn 'has "{category}" "{name}"' apps/cli/templates/
# Search for direct string references
grep -rn '{name}' apps/cli/templates/ --include='*.hbs'
For each hit: read the file, understand the conditional block, document what changes when the library is present vs absent.
Category 4: Tests
grep -rn '{name}' apps/cli/tests/
List test files and what they assert about this library.
Direct templates — API changes, import paths, configuration
Cross-referenced templates — only if the integration API changed
Tests — update assertions if they check specific versions or API patterns
What NOT to change
Don't update unrelated libraries (one at a time)
Don't refactor templates beyond what the breaking change requires
Don't add features that happen to be in the new version
Phase 4 — Verify
Step 1: Run tests
cd apps/cli && bun test
Fix all failures caused by your changes before proceeding. If there are pre-existing test failures (failures that exist on the branch before your changes), document them but don't let them block you — focus on ensuring your update doesn't introduce new failures. Compare test output against a clean run on the branch before your changes if needed.
Step 2: Identify critical combinations
From the Phase 2 cross-references, derive which library/addon combinations produce different template output. Each hasLibrary/has/isMono conditional in an affected file implies a combination to test.
