updating-libraries

name	updating-libraries
description	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
• New peer dependencies or renamed packages

Do NOT use for:

• Adding new libraries (use adding-templates skill)
• Fixing template formatting (use fixing-templates skill)
• 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.

The Process

digraph updating {
    node [fontsize=11];
    edge [fontsize=9];

    "Start" [shape=doublecircle];
    "Phase 1:\nResearch" [shape=box];
    "Breaking changes\nidentified?" [shape=diamond];
    "Phase 2:\nMap Touchpoints" [shape=box];
    "Inventory complete?" [shape=diamond];
    "Phase 3:\nUpdate" [shape=box];
    "Phase 4:\nVerify" [shape=box];
    "Tests pass?" [shape=diamond];
    "Generation builds?" [shape=diamond];
    "Phase 5:\nCommit" [shape=box];
    "Done" [shape=doublecircle];

    "Start" -> "Phase 1:\nResearch";
    "Phase 1:\nResearch" -> "Breaking changes\nidentified?";
    "Breaking changes\nidentified?" -> "Phase 2:\nMap Touchpoints" [label="yes or no\n(always proceed)"];
    "Phase 2:\nMap Touchpoints" -> "Inventory complete?";
    "Inventory complete?" -> "Phase 2:\nMap Touchpoints" [label="no — keep searching"];
    "Inventory complete?" -> "Phase 3:\nUpdate" [label="yes"];
    "Phase 3:\nUpdate" -> "Phase 4:\nVerify";
    "Phase 4:\nVerify" -> "Tests pass?";
    "Tests pass?" -> "Phase 3:\nUpdate" [label="no — fix"];
    "Tests pass?" -> "Generation builds?" [label="yes"];
    "Generation builds?" -> "Phase 3:\nUpdate" [label="no — fix"];
    "Generation builds?" -> "Phase 5:\nCommit" [label="yes"];
    "Phase 5:\nCommit" -> "Done";
}

Hard gates:

• 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.

Produce the inventory

Format:

META: apps/cli/src/__meta__.ts (lines X-Y)
  - version: ^1.4.10
  - deps: better-auth, @repo/db (conditional)
  - envs: BETTER_AUTH_SECRET, BETTER_AUTH_URL
  - require: orm (drizzle|prisma)
  - mono: pkg/auth

Direct templates (N files):
  - templates/libraries/better-auth/src/lib/auth/auth.ts.hbs — server auth init
  - templates/libraries/better-auth/src/lib/auth/auth-client.ts.hbs — client auth
  - ...

Cross-references (N files):
  - templates/project/orm/drizzle/src/schema.ts.hbs — hasLibrary "better-auth" (auth tables)
  - templates/libraries/trpc/src/trpc/init.ts.hbs — hasLibrary "better-auth" (protected procedures)
  - ...

Tests (N files):
  - tests/unit/meta.test.ts — META structure assertions
  - tests/e2e/turbo.test.ts — full generation + build
  - ...

DO NOT proceed to Phase 3 until this inventory is complete and presented.

Phase 3 — Update

Now make changes, guided by the inventory. For each file in the inventory, cross-reference with the Phase 1 research to determine what needs changing.

Update order

1. __meta__.ts — version, dependencies, env vars, exports
2. Direct templates — API changes, import paths, configuration
3. Cross-referenced templates — only if the integration API changed
4. 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.

Example derivation for better-auth:

Cross-ref: drizzle/schema.ts.hbs uses hasLibrary "better-auth"
  → Test: better-auth + drizzle

Cross-ref: prisma/schema.prisma.hbs uses hasLibrary "better-auth"
  → Test: better-auth + prisma

Cross-ref: trpc/init.ts.hbs uses hasLibrary "better-auth"
  → Test: better-auth + trpc

Cross-ref: auth.ts.hbs uses has "orm" "drizzle" / has "database" "postgres"
  → Test: drizzle+postgres AND drizzle+mysql (or prisma variants)

Cross-ref: auth.ts.hbs uses isMono
  → Test: single AND turborepo

Deduplicate into a minimal set of generation commands that covers all conditional branches.

Step 3: Generate and build

For each critical combination:

bunx create-faster test-X --app name:stack:libs --database X --orm X --pm bun
cd test-X && bun install && bun run build

ALL generated projects must build successfully.

Step 4: Clean up

Remove test directories after verification.

Phase 5 — Commit

Choose the commit message based on what changed:

• Version bump only (no template changes): chore(meta): update {name} to {version}
• Template changes needed: feat(templates): update {name} templates for v{version}

Include a brief description of breaking changes addressed in the commit body.

Checklist

Research (Phase 1)

• Used context7 to fetch latest library docs
• Found and read changelog/migration guide
• Documented all breaking changes with specific details
• Documented new/removed/renamed packages

Inventory (Phase 2)

• Read META entry completely
• Listed all direct template files
• Grepped ALL templates for cross-references (hasLibrary, has)
• Grepped tests for references
• Presented complete inventory before making changes

Update (Phase 3)

• Updated version in __meta__.ts
• Updated dependencies (added/removed/renamed packages)
• Updated template import paths and API calls
• Updated cross-referenced templates (only if integration API changed)
• Updated test assertions (if they check versions or API patterns)

Verify (Phase 4)

• bun test passes
• Derived critical combinations from cross-reference conditionals
• Generated test projects for each combination
• bun install && bun run build succeeds for all generated projects
• Cleaned up test directories

Commit (Phase 5)

• Committed with appropriate conventional commit message

Common Rationalizations — STOP

Excuse	Reality
"The user told me what changed, I don't need to research"	Users describe symptoms, not full scope. Check the docs. The changelog may reveal changes they didn't mention.
"I can see the files that need changing"	Browsing finds obvious files. Grep finds cross-references you'd miss. Do the systematic search.
"The old imports probably still work"	Probably = untested assumption. Verify with docs. If backward compat exists, the skill decides whether to use it — not assumptions.
"I'll just bump the version and see what breaks"	That's debugging, not updating. Research first.
"The tests will catch any issues"	Tests catch what they test. They don't test that generated projects actually build with the new version. Generate and verify.
"Testing all combinations is overkill"	Each conditional branch is a different code path in generated output. Test them.
"I'll check cross-references later"	Later = never. The inventory gates all changes.
"This is a minor version, probably no breaking changes"	Minor versions break things all the time. Research anyway.
"I know this library well"	You know the OLD version. The new version may differ. Check context7.
"Tests are already failing, so I can't verify"	Distinguish pre-existing failures from new ones. Your changes must not introduce new failures.

Red Flags — STOP and Re-read This Skill

• You're editing __meta__.ts without having produced a research summary
• You're editing templates without having produced a touchpoint inventory
• You're committing without having generated and built test projects
• You said "probably still works" about any import or API
• You found cross-references by browsing instead of grepping
• You skipped context7 because "the user already explained the changes"
• You're updating more than one library in the same pass

Quick Reference

Phase	Gate	Key commands
1. Research	Must produce research summary	context7 resolve + query-docs, WebFetch/WebSearch
2. Inventory	Must present full inventory	grep -rn 'hasLibrary "{name}"' apps/cli/templates/
3. Update	Guided by inventory	Edit __meta__.ts, templates, cross-refs
4. Verify	Tests → Generation → Build	bun test, bunx create-faster ..., bun run build
5. Commit	All builds pass	git commit