refactoring-shared-component-api
/refactoring-shared-component-api
Use when changing the public API (props, emits, slots, events, exported signatures) of a UI component or module consumed in 2+ places - renaming a prop, removing a parameter, changing a contract - "change this shared component's API", "change l'API de ce composant partagé", "rename this prop", "renomme cette prop". Also use when a typecheck passes but the change touches a shared contract.
- Author
- charierefiedler ↗
- Repository
- ronce-racine ↗
- Licence
- MIT
- Last repository change
- 22.10.2026
Assessment and security
- Files in this package
- 3
- Scripts
- 1
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 22.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
- 1 scripts in this package. Review them before installing, as Claude may execute them.
Scripts: scripts/sweep-call-sites.ts
What it does and when to use it
Use when changing the public API (props, emits, slots, events, exported signatures) of a UI component or module consumed in 2+ places - renaming a prop, removing a parameter, changing a contract - "change this shared component's API", "change l'API de ce composant partagé", "rename this prop", "renomme cette prop". Also use when a typecheck passes but the change touches a shared contract.
Triggers from the description
Original author description
Use when changing the public API (props, emits, slots, events, exported signatures) of a UI component or module consumed in 2+ places - renaming a prop, removing a parameter, changing a contract - "change this shared component's API", "change l'API de ce composant partagé", "rename this prop", "renomme cette prop". Also use when a typecheck passes but the change touches a shared contract.
How it works
- This skill vs. others
- Principle
- Context to gather (before acting)
- Checklist (mandatory order, no step is optional)
- Templates
- Traps & rationalizations
- Exit condition
- Tooling
SKILL.md preview
---
name: refactoring-shared-component-api
description: Use when changing the public API (props, emits, slots, events, exported signatures) of a UI component or module consumed in 2+ places - renaming a prop, removing a parameter, changing a contract - "change this shared component's API", "change l'API de ce composant partagé", "rename this prop", "renomme cette prop". Also use when a typecheck passes but the change touches a shared contract.
version: 1.0.3
metadata:
last-reviewed: 2026-08-08
category: frontend
---
# Refactoring a shared component's API
> If the current repo has a dedicated skill or conventions for this case, they win.
## This skill vs. others
- **This skill** when: changing the public API (props/emits/slots/events/exported signature) of a component or module consumed in 2+ places
- **frontend-spec-call-site-audit** instead if: specifying a new feature, not changing an existing contract
- **writing-robust-tests** alongside: to write the integration-point tests in step 4
## Principle
A shared-API refactor is **not done when the typecheck passes**: it is done when **every grepped call site** is migrated or justified. Many frameworks (Vue fallthrough attrs, dynamic JS, untyped templates) silently accept an unknown prop/argument - no compile, typecheck, or runtime signal.
## Context to gather (before acting)
- Does the compiler check templates strictly (`strictTemplates`, typed JSX)? If not, the silent-contract check in step 3 is **manual and mandatory**
- Typecheck + test commands: read `package.json` / `Cargo.toml` / CI
- Locate existing compatibility wrappers around the component - these are the most often forgotten consumers
## Checklist (mandatory order, no step is optional)
### 1. Exhaustive sweep BEFORE touching the component - `scripts/sweep-call-sites.ts`
- Grep every call site - all casings (`<MyBadge`, `<my-badge`), dynamic usages (`:is=`, factories), object spreads (`v-bind="obj"`, `{...props}`)
- **Compatibility wrappers are first-class call sites** - the wrapper whose only job is to preserve the old interface is the most often forgotten consumer
- Include: stories/fixtures/mocks, docstrings that reference the old API
- List every call site; that is the migration checklist
### 2. Migration
- Migrate each listed call site, ticking them off as you go
- For each removed or renamed prop/parameter: grepping the old name must return **0 occurrences** among consumers
### 3. Silent-contract check
- For each migrated call site: open the consumed component and verify that **every prop/argument passed is declared** in its interface
- If the compiler checks templates strictly (e.g. `strictTemplates`), the typecheck is enough; otherwise this check is **manual and mandatory**
### 4. Integration-point tests
- Every wrapper/adapter touched gets its **own mount test** (the event bubbles up, the prop drives the render) - these bugs are invisible until a human exercises the feature
### 5. Validation
- Unit tests + typecheck; verify the existing tests actually exercise the prop name (a test on a CSS class passes even if the rename is incomplete)
## Templates
- `templates/migration-checklist.md` - migration checklist to paste into the MR (call sites + status)
## Traps & rationalizations
| Excuse | Reality |
|--------|---------|
| "The typecheck passes, it's done" | Fallthrough attrs, dynamic JS, and untyped templates accept an unknown prop without complaint. The call-site sweep is authoritative. |
| "The compat wrapper isn't really a call site" | It's the most often forgotten consumer, and its only job is to carry the old interface. Sweep mandatory. |
| "A global sed on `variant` will be faster" | A generic name touches unrelated components. Migrate file by file. |
| "The existing tests pass" | A test on a CSS class passes even if the rename is incomplete. Verify they exercise the prop name. |
## Exit condition
- [ ] Exhaustive sweep run (`scripts/sweep-call-sites.ts`), all call sites listed
- [ ] Each call site migrated or justified (not affected); grep of the old name = **0 occurrences** among consumers
- [ ] Silent-contract check done (every prop passed is declared in the component's interface)
- [ ] Mount test on each wrapper/adapter touched
- [ ] Tests + typecheck run, output pasted - never "it should pass"
- [ ] Deliverable: list of call sites + status (migrated / removed / not affected, justified)
## Tooling
- Test procedure: `scripts/sweep-call-sites.test.ts` - deterministic behavioral test of the script (positive + negative fixture). Run `npx tsx scripts/sweep-call-sites.test.ts` from the canonical repo after any change to the script (also picked up by `npm test`). Not distributed to target repos.
- `scripts/sweep-call-sites.ts <ComponentName> [rootDir]` - automatic sweep (casings, dynamic usages, spreads, **suspicious wrappers highlighted**, stories/mocks), output = markdown checklist
Files in this package (3)
- SKILL.md 5 KB
- scripts/sweep-call-sites.ts 4 KB
- templates/migration-checklist.md 1 KB
Versions
The database has no other skills named refactoring-shared-component-api.
Identical content appears in 1 other GitHub folders. We show one copy with the highest score.
Database snapshot: 13.11.2026 · package version d8339f64376f (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 86change-an-api
Use when changing what a route accepts or returns, when removing or renaming a field, or when a client needs something a published version does not give. - 100cross-module-impact-scanner
Classifies how a proposed change affects each consuming module's public surface and recommends coordinated changes. Use when a graduated or full lane change touches a public API, event, shared table, shared config value or re-exported utility. - 100frontend-ui-engineering
Front-load UI construction decisions — component boundary and prop API, state placement, required states, responsiveness, accessibility. Use when creating or refactoring a component, page, or design-system primitive. Don't use for pure logic (/tdd), throwaway exploration… - 85component-api-design
Use when designing or reviewing a component's public API. Naming, props, compound component structure, CSS custom properties, and data-attributes. - 91vue-component-patterns
Use when Vue component patterns including props, emits, slots, and provide/inject. Use when building reusable Vue components. - 90component-api-stability
Keep a UI component's props, events, slots and CSS hooks stable for consumers - classify each API change as breaking or safe, add deprecation paths instead of removals, and keep the surface small. Use when changing a shared component or design-system library, reviewing a…