js-to-typescript-migration

name	js-to-typescript-migration
description	Analyze JavaScript projects end-to-end and produce a comprehensive TypeScript migration report. Scans all dependencies (npm/yarn), bundler config (webpack v5, Vite, Rollup, esbuild, Parcel), build pipelines, and source code patterns. Searches online for type availability (@types/* packages), known migration blockers, and community guidance. Generates a prioritized, safe migration plan. WHEN: migrate JS to TypeScript, convert JavaScript to TypeScript, TypeScript migration report, JS to TS assessment, check type coverage, analyze dependencies for TypeScript, webpack TypeScript migration, convert project to TypeScript, type safety audit, add TypeScript to existing project, modernize JavaScript project.
license	MIT
metadata	{"author":"custom","version":"1.0.0"}

JavaScript → TypeScript Migration Analyzer

Deep-analysis skill that inspects a JS project's source, dependencies, bundler config, and build pipeline — then searches online for type availability and known issues — to produce a safe, prioritized migration plan.

Triggers

Activate this skill when user wants to:

• Assess a JavaScript project for TypeScript migration
• Generate a migration readiness report
• Check if all npm dependencies have type definitions
• Understand what would break when converting to TypeScript
• Get a step-by-step safe migration plan
• Migrate a webpack v5 project to TypeScript
• Convert bundler config (webpack/Vite/Rollup) to TypeScript
• Audit type coverage of an existing JS/TS hybrid project

Rules

1. Never modify source files during the assessment phase — read-only analysis only
2. Follow phases sequentially — do not skip
3. Always produce a written report before any code changes
4. Use web search to verify type availability for every dependency
5. Flag breaking changes and risk levels explicitly
6. Respect existing build tooling — propose incremental migration, not rewrites
7. Ask user before any destructive or irreversible action

Assessment Phases

Phase 1: Project Discovery

Gather project metadata:

1. Read package.json — extract all dependencies and devDependencies
2. Detect package manager — check for package-lock.json, yarn.lock, pnpm-lock.yaml, bun.lockb
3. Detect bundler — scan for webpack.config.*, vite.config.*, rollup.config.*, .babelrc, babel.config.*, esbuild usage, parcel in scripts
4. Detect existing TS — check for tsconfig.json, .ts/.tsx files, @types/* packages already installed
5. Detect linting — check for .eslintrc.*, eslint.config.*, prettier config
6. Detect test framework — jest, vitest, mocha, cypress, playwright configs
7. Count source files — tally .js, .jsx, .ts, .tsx, .mjs, .cjs files by directory

Phase 2: Dependency Type Audit

For every dependency in dependencies and devDependencies:

1. Check if the package ships its own types (has types or typings field in its package.json, or includes .d.ts files)
2. Check if a @types/<package> exists on npm — use web search: site:npmjs.com @types/<package>
3. Check if the package is TypeScript-native (written in TS, types are built-in)
4. Classify each dependency:
   • ✅ Types available — built-in or @types/* exists
   • ⚠️ Partial types — types exist but are outdated or incomplete
   • ❌ No types — need to create a local .d.ts declaration file
   • 🔄 Needs upgrade — newer version has types but current version doesn't

Output a Dependency Type Coverage Table:

Package	Version	Type Source	Status	Action Required
react	18.2.0	@types/react	✅	Install @types/react
lodash	4.17.21	@types/lodash	✅	Install @types/lodash
custom-lib	1.0.0	none	❌	Create local .d.ts

Phase 3: Bundler & Build Pipeline Analysis

Analyze the build configuration in depth:

1. Identify bundler version and all plugins/loaders in use
2. Map loader chain — which loaders handle .js/.jsx and what needs to change for .ts/.tsx
3. Check for TypeScript loader compatibility — ts-loader, babel-loader with @babel/preset-typescript, esbuild-loader, swc-loader
4. Analyze resolve configuration — file extensions, aliases, module resolution
5. Check for code splitting — dynamic imports, lazy loading patterns
6. Review source maps — current config and what changes for TS
7. Analyze environment variables — process.env usage, .env files, DefinePlugin

For webpack v5 specifically, follow webpack v5 migration guide.

For Vite projects, follow Vite migration guide.

Phase 4: Source Code Pattern Analysis

Scan source files for patterns that need special handling:

1. Dynamic imports — require(), import(), conditional requires
2. Module systems — CommonJS vs ESM vs mixed
3. Global augmentations — window.*, global.*, prototype extensions
4. Implicit any patterns — functions without parameter types, arguments usage
5. Duck typing — object spread patterns, dynamic property access
6. Callback patterns — event handlers, middleware chains
7. Third-party integrations — SDK usage patterns, API clients
8. Config files — JS-based configs that may need .ts equivalents
9. Test files — test patterns that need type-aware migration

Phase 5: Risk Assessment & Migration Plan

Produce the final report with:

1. Executive Summary — overall readiness score (0-100), estimated effort, key blockers
2. Risk Matrix:

Risk	Impact	Likelihood	Mitigation
Untyped dependency X	High	Certain	Create local .d.ts
Dynamic require() in Y	Medium	Likely	Refactor to static import
Webpack loader chain	Low	Unlikely	Swap babel-loader preset

3. Migration Order — files ordered by dependency graph (leaves first):

   • Utility/helper files (no imports from project)
   • Shared types and interfaces
   • Service/API layer
   • State management
   • Components (bottom-up)
   • Entry points and config

4. Step-by-Step Plan:

   • Step 1: Install TypeScript and create tsconfig.json
   • Step 2: Install all @types/* packages
   • Step 3: Update bundler config for TS support
   • Step 4: Rename files incrementally (.js → .ts, .jsx → .tsx)
   • Step 5: Fix type errors per file (ordered by dependency graph)
   • Step 6: Enable stricter compiler options progressively
   • Step 7: Update CI/CD pipeline
   • Step 8: Update linting config (@typescript-eslint)

5. tsconfig.json recommendation — tailored to the project:

   • Start with strict: false — enable strict options one by one
   • Configure allowJs: true for incremental migration
   • Set appropriate target, module, moduleResolution
   • Configure path aliases to match bundler aliases

Output Files

All output goes to <project-root>/ts-migration-report/:

• migration-report.md — full assessment report
• dependency-audit.md — detailed dependency type coverage
• bundler-migration.md — bundler-specific migration steps
• recommended-tsconfig.json — starter tsconfig
• migration-checklist.md — actionable checklist

Tools Used

Tool	Purpose
File system tools	Read project files, configs, source code
Web search	Check npm for @types packages, search for known issues
Terminal	Run npm ls, npx tsc --noEmit, dependency checks
Subagents	Parallel dependency auditing, file scanning

Error Handling

Error	Remediation
No package.json found	Ask user to specify project root
Private registry packages	Skip online check, flag for manual review
Monorepo detected	Analyze each workspace package separately
Circular dependencies	Flag in report, suggest refactoring approach

Best Practices

• Always recommend incremental migration (allowJs: true) over big-bang rewrites
• Prefer @babel/preset-typescript or esbuild over ts-loader for faster builds
• Start with strict: false and enable strict options one at a time
• Use // @ts-check JSDoc comments as an intermediate step for critical files
• Set up CI type-checking (tsc --noEmit) before converting files
• Keep any escape hatches temporarily — track them and eliminate progressively