# Typescript Refactor

> Refactor JavaScript to strict TypeScript or audit types - incremental .js to .ts with explicit return types

- Skill: `bh611627/typescript-refactor` (Agent Skill)
- Install (CLI): `npx skillmds@latest add bh611627/typescript-refactor`
- Raw SKILL.md: https://api.skillmd.com/api/skills/bh611627/typescript-refactor/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: bh611627 (https://skillmd.com/u/bh611627)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/bh611627/typescript-refactor

---


# Instructions

Help the user migrate a React/Next.js codebase from JavaScript to **strict TypeScript**.

**Before edits:** suggest `pnpm exec tsc --noEmit` (or `npx tsc --noEmit`) so there is a baseline.
## When to Use

- Use for JS→strict TypeScript or type audits.
- Prefer `code-assistant` for small non-migration diffs.
- Prefer `testing-agent` to lock behavior before refactors.


## Mode A - full file refactor

1. Ensure `tsconfig.json` has `"strict": true` (and `"noImplicitAny": true` if split).
2. Rename target `.js`/`.jsx` → `.ts`/`.tsx` one module at a time (smallest leaf first).
3. Infer props and state; add **explicit return types** on exported functions and hooks.
4. Replace `any` with `unknown`, generics, or narrow types; use type guards where needed.
5. For large repos, optional **ts-morph** codemods - list files touched.
6. Update imports and `package.json` types field if missing.
7. Re-run `tsc --noEmit` and fix errors until clean for touched scope.

## Mode B - audit only

1. Scan `src/` for `.js`/`.jsx` remaining.
2. Report `file:line` for: implicit `any`, missing return types, `@ts-ignore`, unsafe casts.
3. Prioritize entry points and shared utilities.
4. No file writes - deliver a markdown table grouped by severity.

## Outcomes

- **Mode A:** converted files + strict config + `tsc --noEmit` instructions.
- **Mode B:** prioritized audit report with estimated effort per file.

## Output Rules

State mode. List files changed or audited. Include the exact `tsc` command used.

## Scope and boundaries

- **In scope:** TypeScript migration, typing, strict config for frontend/Next repos.
- **Out of scope:** backend language migrations, changing runtime behavior beyond types, mass delete/refactor without user scope.

## Safety

- **Mode A** modifies source files; user should commit first and run `tsc --noEmit` before applying.
- Do not print `.env` values; do not run destructive shell without user approval.
- Match the project lockfile (`pnpm-lock.yaml` → pnpm).

## Troubleshooting

- **RSC errors after rename:** ensure server files avoid client-only APIs; add `"use client"` only where hooks are required.
- **`any` explosion:** narrow one module at a time; use `satisfies` and discriminated unions before generics everywhere.
- **ts-morph version mismatch:** align `typescript` devDependency with the project’s installed version.

## Related skills

- [`code-assistant`](../code-assistant/SKILL.md) - scoped TS fixes
- [`testing-agent`](../testing-agent/SKILL.md) - type-safe tests
- [`pr-review-workflow`](../pr-review-workflow/SKILL.md) - review type migrations

**GitHub:** https://github.com/bh611627/skillcodex/tree/main/skills/typescript-refactor/SKILL.md  
**npm:** https://www.npmjs.com/package/@skillcodex/skills