migrate-js-to-modern-typescript — Claude Code skill: how to install
migrate-js-to-modern-typescript guides the file-by-file conversion of a JavaScript codebase to strict TypeScript. Helps configure tsconfig, turn on strict compiler flags, and eliminate any without breaking the build.
MIT 145 installs ★ 227 updated 2026-08-15
npx skills add pproenca/dot-skills --skill migrate-js-to-modern-typescript -a claude-codeWhat migrate-js-to-modern-typescript does
The skill supplies 42 rules divided into 7 prioritized categories to move code to strict TypeScript. Instead of rewriting everything at once, it works file by file. The migration begins with tsconfig flags like allowJs and checkJs, then ratchets up compiler checks including noImplicitAny and strictNullChecks.
It directs the agent to replace any and unsafe as casts with unknown and runtime narrowing. Modules move from CommonJS to ESM, while prototypes turn into classes. Runtime boundaries such as environment variables and API responses get explicit schema validation.
A top-down conversion order creates problems because upstream modules get typed before their dependencies stabilize. The rules enforce working from the leaves of the dependency tree inward. This preserves a passing build at every step.
What it helps with
- migrate a JavaScript codebase to TypeScript incrementally without build breaks
- enable strict compiler flags like strictNullChecks and noImplicitAny
- replace unsafe as casts and any annotations with unknown narrowing
- convert CommonJS modules and prototypes to modern ESM and classes
Example prompts for the agent
- Convert
utils/format.jsto TypeScript and add strict types - Turn on strict mode in our tsconfig and fix the resulting errors
- Replace all any and as casts in
src/api.tswith unknown and type guards
How to install migrate-js-to-modern-typescript
1Skills CLI (Vercel)
npx skills add pproenca/dot-skills --skill migrate-js-to-modern-typescript -a claude-code2Manually: put the files in place
~/.claude/skills/migrate-js-to-modern-typescript/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/migrate-js-to-modern-typescript/
1Skills CLI (Vercel)
npx skills add pproenca/dot-skills --skill migrate-js-to-modern-typescript -a codex2Manually: put the files in place
.agents/skills/migrate-js-to-modern-typescript/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add pproenca/dot-skills --skill migrate-js-to-modern-typescript -a cursor2Manually: put the files in place
.cursor/skills/migrate-js-to-modern-typescript/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install pproenca/dot-skills skills/.experimental/migrate-js-to-modern-typescript2Manually: put the files in place
.github/skills/migrate-js-to-modern-typescript/SKILL.md1Skills CLI (Vercel)
npx skills add pproenca/dot-skills --skill migrate-js-to-modern-typescript -a gemini-cli2Platform CLI
gemini skills install https://github.com/pproenca/dot-skills --path skills/.experimental/migrate-js-to-modern-typescriptManually: put the files in place
.devin/skills/migrate-js-to-modern-typescript/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add pproenca/dot-skills --skill migrate-js-to-modern-typescript -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about migrate-js-to-modern-typescript
How to install migrate-js-to-modern-typescript in Claude Code?
Run npx skills add pproenca/dot-skills --skill migrate-js-to-modern-typescript -a claude-code in your terminal.
What does migrate-js-to-modern-typescript do?
It gives your AI assistant a 42-rule workflow for migrating JavaScript projects to strict TypeScript. The guidelines cover tsconfig setup, strictness ratcheting, typing public surfaces, and build tooling.
What conversion order does the skill enforce?
It converts leaf files in the dependency graph first before moving inward. Starting at the top causes duplicate typing work as lower-level types shift.
Source text
SKILL.md · MIT
--- name: migrate-js-to-modern-typescript description: Migrating a JavaScript codebase to TypeScript — converting .js files to .ts, adding types to existing JS, or tightening a loosely-typed TS project toward strict mode. Covers tsconfig and allowJs strategy, incremental strict-flag ratcheting (noImplicitAny, strictNullChecks, noUncheckedIndexedAccess), typing public surfaces, replacing `any` and unsafe casts with `unknown` and narrowing, validating runtime boundaries (JSON, env, API responses), converting CommonJS to ESM and prototypes to classes, and the build/CI changes a migration needs. Trigger even when the user only says "add types", "turn on strict mode", or "convert this file to TypeScript", and especially on a mixed JS/TS repo. Distinct from general TypeScript refactoring — this is the migration act itself, performed file by file while keeping the build green. --- # JavaScript to TypeScript Migration Best Practices Guide for taking a JavaScript codebase to strict, modern TypeScript without a big-bang rewrite. Contains 42 rules across 7 categories, prioritized by impact to drive an incremental, file-by-file migration that keeps the build compiling at every step. ## When to Apply Reference these guidelines when: - Converting a `.js` codebase to `.ts` (whole project or one module at a time) - Adding types to existing JavaScript via JSDoc or annotations - Choosing a `tsconfig` and `allowJs` strategy for a mixed JS/TS repo - Turning on `strict` mode or individual strict flags on a large codebase - Replacing `any`, `as` casts, and `!` assertions left over from a quick conversion - Validating external data (JSON, env, API responses) so the types you wrote are true at runtime - Converting CommonJS to ESM, prototypes to classes, and other JS idioms to TS - Updating the build, runner, and CI to type-check and publish TypeScript ## How the Migration Flows ``` tsconfig & strategy → strictness ratchet → type the surfaces → kill any/casts → validate runtime boundaries → convert JS idioms → tooling/build/CI ``` Decisions at the front cascade: a wrong `tsconfig` or a top-down conversion order forces you to re-type modules twice, and an early `any` flood poisons everything downstream. Work from the front of this pipeline and from the leaves of the dependency graph inward. ## Rule Categories by Priority | Priority | Category | Impact | Prefix | |----------|----------|--------|--------| | 1 | Migration Setup & tsconfig | CRITICAL | `setup-` | | 2 | Strictness Ratcheting | CRITICAL | `strict-` | | 3 | Typing Public Surfaces | HIGH | `surface-` | | 4 | Replacing `any` & Unsafe Casts | HIGH | `unsafe-` | | 5 | Runtime Data Validation | MEDIUM-HIGH | `runtime-` | | 6 | JS-to-TS Idiom Conversion | MEDIUM | `idiom-` | | 7 | Tooling & Build Migration | LOW-MEDIUM | `tooling-` | ## Quick Reference ### 1. Migration Setup & tsconfig (CRITICAL) - [`setup-allowjs-checkjs-bridge`](references/setup-allowjs-checkjs-bridge.md) — Enable allowJs and checkJs for incremental migration - [`setup-migrate-leaves-first`](references/setup-migrate-leaves-first.md) — Convert dependency leaves before their dependents - [`setup-jsdoc-before-rename`](references/setup-jsdoc-before-rename.md) — Type JS with JSDoc and @ts-check before renaming - [`setup-prefer-ts-expect-error`](references/setup-prefer-ts-expect-error.md) — Prefer @ts-expect-error over @ts-ignore for suppressions - [`setup-skiplibcheck-during-migration`](references/setup-skiplibcheck-during-migration.md) — Set skipLibCheck to silence third-party type noise - [`setup-modern-module-resolution`](references/setup-modern-module-resolution.md) — Set module and moduleResolution to a modern pair - [`setup-noemitonerror-isolatedmodules`](references/setup-noemitonerror-isolatedmodules.md) — Enable isolatedModules and noEmitOnError for safe output ### 2. Strictness Ratcheting (CRITICAL) - [`strict-enable-flags-incrementally`](references/strict-enable-flags-incrementally.md) — Enable strict flags one at a time, not all at once - [`strict-prioritize-null-checks`](references/strict-prioritize-null-checks.md) — Prioritize strictNullChecks for the highest bug yield - [`strict-no-implicit-any`](references/strict-no-implicit-any.md) — Enable noImplicitAny to surface every untyped value - [`strict-no-unchecked-indexed-access`](references/strict-no-unchecked-indexed-access.md) — Enable noUncheckedIndexedAccess for index safety - [`strict-use-unknown-in-catch`](references/strict-use-unknown-in-catch.md) — Type caught errors as unknown, not any - [`strict-exact-optional-property-types`](references/strict-exact-optional-property-types.md) — Separate missing from undefined with exactOptionalPropertyTypes ### 3. Typing Public Surfaces (HIGH) - [`surface-annotate-exported-signatures`](references/surface-annotate-exported-signatures.md) — Annotate exported function signatures explicitly - [`surface-replace-jsdoc-with-types`](references/surface-replace-jsdoc-with-types.md) — Replace JSDoc type tags with real annotations - [`surface-type-default-params`](references/surface-type-default-params.md) — Type default and optional parameters precisely - [`surface-interface-for-object-args`](references/surface-interface-for-object-args.md) — Convert loose object arguments to named interfaces - [`surface-type-callbacks`](references/surface-type-callbacks.md) — Type callback and higher-order parameters - [`surface-type-class-fields`](references/surface-type-class-fields.md) — Declare class field types instead of relying on assignment ### 4. Replacing any & Unsafe Casts (HIGH) - [`unsafe-prefer-unknown-over-any`](references/unsafe-prefer-unknown-over-any.md) — Replace any with unknown at untrusted boundaries - [`unsafe-eliminate-as-casts`](references/unsafe-eliminate-as-casts.md) — Replace as casts with narrowing or validation - [`unsafe-avoid-double-assertion`](references/unsafe-avoid-double-assertion.md) — Avoid double assertions that force unrelated types - [`unsafe-type-dynamic-property-access`](references/unsafe-type-dynamic-property-access.md) — Type dynamic property access with Records or index signatures - [`unsafe-replace-function-type`](references/unsafe-replace-function-type.md) — Replace the Function type with specific call signatures - [`unsafe-narrow-instead-of-nonnull`](references/unsafe-narrow-instead-of-nonnull.md) — Narrow values instead of using the non-null assertion ### 5. Runtime Data Validation (MEDIUM-HIGH) - [`runtime-validate-external-data`](references/runtime-validate-external-data.md) — Validate external data at the boundary - [`runtime-type-environment-variables`](references/runtime-type-environment-variables.md) — Parse and type environment variables once - [`runtime-derive-types-from-schemas`](references/runtime-derive-types-from-schemas.md) — Derive static types from runtime schemas - [`runtime-type-guards-at-boundaries`](references/runtime-type-guards-at-boundaries.md) — Write type guards for untyped library returns - [`runtime-type-json-parse`](references/runtime-type-json-parse.md) — Type JSON.parse results through validation ### 6. JS-to-TS Idiom Conversion (MEDIUM) - [`idiom-require-to-import`](references/idiom-require-to-import.md) — Convert require and module.exports to ESM syntax - [`idiom-prototype-to-class`](references/idiom-prototype-to-class.md) — Convert prototype constructors to class syntax - [`idiom-type-only-imports`](references/idiom-type-only-imports.md) — Use import type for type-only imports - [`idiom-replace-arguments-object`](references/idiom-replace-arguments-object.md) — Replace the arguments object with rest parameters - [`idiom-enum-to-union-or-const`](references/idiom-enum-to-union-or-const.md) — Convert frozen-object enums to const objects or unions - [`idiom-default-export-to-named`](references/idiom-default-export-to-named.md) — Prefer named exports over default exports - [`idiom-optional-chaining-over-guards`](references/idiom-optional-chaining-over-guards.md) — Replace manual existence guards with optional chaining ### 7. Tooling & Build Migration (LOW-MEDIUM) - [`tooling-declare-untyped-modules`](references/tooling-declare-untyped-modules.md) — Provide ambient declarations for untyped dependencies - [`tooling-install-types-packages`](references/tooling-install-types-packages.md) — Install @types packages before casting library returns - [`tooling-use-tsx-over-ts-node`](references/tooling-use-tsx-over-ts-node.md) — Run TypeScript directly with tsx instead of ts-node flags - [`tooling-emit-declaration-files`](references/tooling-emit-declaration-files.md) — Emit declaration files for migrated libraries - [`tooling-typecheck-in-ci`](references/tooling-typecheck-in-ci.md) — Add a type-check step to CI separate from the build ## How to Use Read individual reference files for detailed explanations and code examples: - [Section definitions](references/_sections.md) — Category structure and impact levels - [Rule template](assets/templates/_template.md) — Template for adding new rules ## Related Skills - `typescript-refactor` — Refactoring and modernizing code that is already TypeScript - `typescript-advanced-patterns` — Advanced type-level patterns once the migration is done ## Reference Files | File | Description | |------|-------------| | [references/_sections.md](references/_sections.md) | Category definitions and ordering | | [assets/templates/_template.md](assets/templates/_template.md) | Template for new rules | | [metadata.json](metadata.json) | Version and reference information |
© pproenca · MIT · pproenca/dot-skills