Skip to content
Skills Library
Programming · Building & coding

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.

Licence
MIT
Last repository change
22.10.2026

Assessment and security

90/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content25 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
3
Scripts
1
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 22.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • 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

change this shared componentchange lrename this proprenomme cette prop
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

  1. This skill vs. others
  2. Principle
  3. Context to gather (before acting)
  4. Checklist (mandatory order, no step is optional)
  5. Templates
  6. Traps & rationalizations
  7. Exit condition
  8. Tooling
Original SKILL.md headings · 71 lines, 669 words
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…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.