experience-lwc-typescript-migrate

Converting LWC to TypeScript

Convert a Lightning Web Component bundle from JavaScript to TypeScript. The deliverable is a fully-typed .ts implementation plus a .d.ts file that only exposes @api members (the public surface other LWCs consume).

When to Use This Skill

• User wants to migrate a single component or a folder of components from .js to .ts.
• User needs a .d.ts for an existing LWC so other components (or an external TypeScript host) can import it safely.
• User is adding type annotations to an already-renamed .ts LWC that hasn't been properly typed yet.
• User wants JSDoc-style type hints upgraded to real TypeScript types.

Prerequisites

• The component builds and runs correctly in JavaScript today.
• git is available (the rename must preserve history via git mv).
• A TypeScript compiler is wired into the build (either the SFDX TS pipeline or a standalone tsc step).

---

Workflow

Step 1 — Read the component

Open every file in the bundle:

componentName/
├── componentName.js
├── componentName.html
├── componentName.css
└── (possibly) __tests__/, __utam__/, existing .d.ts

Understand:

• What extends LightningElement? What is the class name?
• Which fields and methods carry the @api decorator?
• Which properties/methods have existing JSDoc (use as a type hint starting point, but validate against actual usage — JSDoc lies).
• Which parameters / return types can you infer from how the code is called internally?

Step 2 — Rename .js → .ts using git mv

git mv componentName/componentName.js componentName/componentName.ts

Repeat for any helper .js files in the bundle (unless they're already .ts). Never plain mv — that loses the history link TypeScript reviewers rely on.

Step 3 — Add type annotations in the .ts

Apply types in this priority order so you stop as soon as the public contract is solid:

1. @api properties and methods first. Generate JSDoc if it's missing, then translate JSDoc types to TS syntax (string, number, boolean, Promise<T>). Validate each JSDoc claim against the code before trusting it.
2. Complex shapes become interface or type aliases — not inline shapes repeated everywhere.
3. Optional members use ? only when the value is genuinely allowed to be undefined. Do not sprinkle ? defensively.
4. Private/internal state — still type it, but don't export the types. Use private for members that must never be touched by consumers.
5. Event handlers — prefer precise DOM event types:
   • MouseEvent for onclick (and other click-like handlers). click is dispatched as a MouseEvent — including keyboard-activated clicks — so typing it as PointerEvent would let handlers rely on pointer-only fields (pointerType, pressure, etc.) that are undefined in those cases.
   • PointerEvent for onpointerdown / onpointerup / onpointermove and other pointer* handlers where pointer-specific fields are actually meaningful.
   • CustomEvent<{ detail: ... }> for LWC custom events.
   • Event is the last resort; document why when using it.
6. Async methods always return Promise<T> — never bare T.
7. Avoid any. If you genuinely can't type something, use unknown and narrow with a type guard.