A JavaScript to TypeScript migration does not need to be a rewrite or a pause in feature work. This guide provides a file-by-file plan using inventory, incremental compiler settings, runtime tests, declaration files, and risk-based batches so your team can improve type safety without destabilizing the application.
Overview
The safest way to migrate JavaScript to TypeScript is to make the compiler part of the existing workflow before converting large amounts of code. Start by measuring the codebase, enable TypeScript to understand JavaScript files, and then move boundaries and high-value modules into .ts or .tsx in small batches.
A useful migration has two separate goals:
- Build confidence: preserve behavior through tests, smoke checks, and small pull requests.
- Improve guarantees: replace implicit assumptions with explicit types, safer module contracts, and stricter compiler checks.
Do not treat “zero errors” as the only measure of progress. A codebase can compile while still accepting invalid API data, hiding unsafe casts, or lacking tests around important behavior. Track converted files, reduced type escapes, covered boundaries, and the strictness milestones your team has agreed to complete.
Before changing configuration, record the current build, test, lint, and deployment commands. If the project uses React, Next.js, Node.js, a custom bundler, or a package build, verify how each tool discovers extensions, resolves modules, handles ESM and CommonJS, and emits output. For a broader configuration checklist, see the TypeScript tsconfig guide.
A practical migration decision tree
- Can the current application build and test reliably? If not, stabilize those workflows first. A migration should not hide unrelated failures.
- Does the project need gradual adoption? For an actively developed application, use
allowJsand considercheckJs. A small, isolated package may be able to convert directly. - Are module boundaries documented? If not, begin with shared types and public interfaces rather than randomly renaming files.
- Does a file have strong tests and limited dependencies? Convert it early. If it is a central, weakly tested module, add characterization tests before changing its types.
- Does a dependency lack usable types? Check for a declaration package, inspect its actual exports, and use a narrow local declaration only as a documented temporary bridge.
Checklist by scenario
For an actively developed application
- Create a migration branch or a small set of independently reviewable tasks.
- Inventory JavaScript files, entry points, build scripts, tests, generated files, and vendored code.
- Add TypeScript without requiring every existing file to be converted.
- Use
allowJs: trueto let JavaScript and TypeScript participate in the same project where the toolchain supports it. - Use
checkJs: trueglobally only when the team is ready for the resulting diagnostics. Otherwise, opt individual files in with// @ts-check. - Convert leaf modules, tested utilities, and stable data models before application entry points.
- Run build, lint, unit tests, integration tests, and a representative production-like check after each batch.
- Prevent new untyped code from expanding the migration surface. For example, document which directories accept new JavaScript and which do not.
For a library or shared package
- Identify the public API before converting implementation details.
- Define exported function parameters, return values, options, errors, and event payloads deliberately.
- Confirm the package’s module format, declaration output,
exportsmap, and type entry point work for its consumers. - Test the package from a consumer-like project rather than relying only on its local source build.
- Keep internal migration changes separate from public API changes when possible.
Declaration files can bridge a JavaScript dependency or an unconverted module, but they should describe reality rather than silence the compiler. For package-specific checks, use this TypeScript package publishing guide.
For a React or frontend codebase
- Convert shared data types and utility functions before highly dynamic components.
- Type component props, callback parameters, and state transitions at their boundaries.
- Check event types and ref usage rather than broadly casting event targets or component instances.
- Verify the framework’s build, test, server-rendering, and client-only paths separately.
- Keep generated route files, build output, and framework-managed directories outside the migration batch unless the framework requires otherwise.
The same principle applies to TypeScript with React: make component APIs explicit, then let implementation errors guide the next conversion. See the React and TypeScript guide for boundary patterns.
For a Node.js service or API
- Map external inputs: HTTP bodies, query strings, headers, environment variables, queues, and database results.
- Separate compile-time types from runtime validation. TypeScript cannot validate unknown JSON after deployment.
- Convert request handlers after defining input and output contracts, not before.
- Test error paths, authentication failures, malformed payloads, and configuration problems.
- Confirm the runtime’s module resolution and emitted output match the deployment command.
For external data, pair static types with explicit parsing or validation. A type assertion such as payload as User does not inspect the payload; it only changes what the compiler assumes.
Risk-based batch checklist
- Low risk: pure utilities, formatting helpers, constants, isolated tests, and well-covered leaf modules.
- Medium risk: shared hooks, service adapters, state modules, and data transformation code.
- High risk: authentication, payment flows, persistence, public package exports, startup configuration, and modules with many consumers.
Convert low-risk modules first to establish conventions. For medium- and high-risk modules, add tests and document assumptions before changing extensions. A migration checklist can help teams apply the same gate to every batch: JavaScript to TypeScript migration checklist.
What to double-check
Compiler settings and strictness milestones
Begin with settings that allow the existing project to participate, then tighten deliberately. A typical progression is:
- Compile or check a representative sample without changing runtime behavior.
- Enable strictness for newly converted files or a bounded project area.
- Address nullability, implicit values, and unsafe indexing rather than suppressing every diagnostic.
- Raise the strictness baseline once the current batch is stable.
Review options such as strict, noImplicitAny, strictNullChecks, noUncheckedIndexedAccess, noImplicitReturns, and unused-code checks according to the project’s risk profile. Do not copy a configuration from another repository without checking its module target, library definitions, JSX mode, paths, declaration settings, and build pipeline.
JavaScript checking and declaration files
allowJs permits JavaScript files in a TypeScript project; it does not make those files fully typed. checkJs asks TypeScript to report problems in JavaScript files, which can expose useful issues but may produce substantial work in a legacy codebase. Use file-level comments or directory-level project boundaries when gradual adoption is more practical.
Use .d.ts files for stable descriptions of modules that cannot yet be converted or whose types come from an external boundary. Keep declarations narrow, name any intentional looseness, and replace temporary declarations when the implementation becomes available.
Dependencies, tests, and tooling
For each dependency, confirm whether it ships types, has a maintained declaration package, or needs a local declaration. Inspect the package’s real import and export shape; a type definition that compiles is not proof that the runtime import works.
Run tests before and after each batch. Add characterization tests where behavior is unclear, especially around coercion, default values, error handling, and asynchronous control flow. Keep ESLint and formatting rules aligned with the migration plan rather than enabling a large set of new warnings at the same time. The TypeScript ESLint setup guide covers a maintainable lint workflow.
Common compiler errors and practical remedies
| Diagnostic pattern | What it usually means | Practical remedy |
|---|---|---|
Implicit any | A parameter or value has no reliable inferred type. | Type the boundary, improve the surrounding inference, or use an intentional narrow type. Avoid adding any merely to clear the error. |
Possibly undefined or null | The code assumes a value exists when the type says it may not. | Handle the missing case, validate earlier, provide a safe default, or narrow with a condition. |
| Property does not exist on type | The object shape is incomplete, incorrectly modeled, or being accessed before narrowing. | Define the actual union or interface and narrow it with a discriminant or runtime check. |
| Module has no declaration file | The dependency or local JavaScript module has no discoverable types. | Install an appropriate declaration package when available or write a focused temporary .d.ts file. |
| Argument is not assignable | A function contract and its caller disagree. | Decide which contract is correct, then update the caller, implementation, or shared type rather than forcing a cast. |
| Module or path cannot be found | TypeScript’s resolution differs from the runtime or bundler configuration. | Check extensions, aliases, moduleResolution, package exports, casing, and the actual build command. |
When a diagnostic is difficult to interpret, consult a focused troubleshooting reference such as TypeScript error messages explained instead of suppressing it without understanding the cause.
Common mistakes
- Renaming every file in one pass: this creates a large review surface and makes runtime regressions difficult to isolate.
- Using
anyas the migration strategy: temporary escape hatches can be useful, but label them and track their removal. - Confusing compile-time types with runtime validation: API responses, configuration, and persisted data still need runtime checks.
- Ignoring module behavior: an import that satisfies the type checker may still fail under the deployed Node.js or bundler configuration.
- Changing semantics while changing types: avoid refactoring control flow, data formats, and module boundaries in the same small migration pull request unless the change is necessary.
- Skipping tests because the compiler is green: types catch structural mistakes, not every behavior change.
- Creating broad declarations for untyped packages:
declare module "*"can hide spelling and package-boundary mistakes across the application. - Leaving migration rules undocumented: contributors need to know which files may remain JavaScript, which strictness level applies, and how new work should be typed.
When to revisit
Revisit this plan before each seasonal planning cycle, after a major framework or build-tool change, and whenever the project adds a new package boundary, runtime, or deployment target. The assumptions behind module resolution, declaration output, test integration, and generated files can change even when application code does not.
Use this short review at every migration milestone:
- Is the current build and test command still the command used in CI and production?
- Have new JavaScript files or untyped dependencies expanded the migration surface?
- Do the current
tsconfigsettings match the runtime, bundler, and package format? - Are temporary declarations, assertions, and
anyvalues documented and assigned for removal? - Did the last batch improve a meaningful boundary, or only change file extensions?
- Is the next batch small enough to review and roll back safely?
Finish each batch by recording converted files, remaining risks, compiler flags enabled, test coverage added, and the next recommended group. That simple record turns a one-time JavaScript to TypeScript migration into a repeatable engineering process—one that can continue alongside feature development and be recalibrated when the surrounding tools change.