Can You Mix JavaScript and TypeScript: A Practical Guide

Learn how to safely combine JavaScript and TypeScript in a single project. This guide covers interop techniques, migration patterns, and best practices for hybrid codebases.

JavaScripting Team

February 25, 2026·5 min read

JavaScript Tutorials Learn JavaScript Frontend Typescript vs JavaScript

can you mix javascript and typescript

can you mix javascript and typescript is the practice of using JavaScript and TypeScript together in one project, typically by writing TypeScript that compiles to JavaScript and by integrating JavaScript libraries with type support. It covers when and how to mix code safely and effectively.

can you mix javascript and typescript

The modern frontend landscape often starts with JavaScript and gradually introduces TypeScript. The idea is to keep existing JS code while adding TS files, step by step, until type safety is sufficient. This approach helps teams avoid large rewrites and preserves momentum while improving reliability over time. You can keep both languages in the same project and configure your tooling to handle them together. In practice, you will see projects with a mix of .js and .ts files coexisting, each contributing to a safer, more maintainable codebase.

How interoperability works

Interoperability hinges on a small set of compiler options and project structure. The key options are allowJs, which lets the TypeScript compiler accept JavaScript files, and checkJs, which enables type checking for JS using JSDoc annotations or ambient declarations. This pairing lets you import JS modules in TS and gradually annotate JS where it matters most. In practice, you place both .ts and .js files under the same source tree and run a single TypeScript build that outputs JavaScript to your dist or build folder. With careful structure, you get the best of both worlds: type safety where it counts and continued compatibility with legacy code.

Practical patterns for a hybrid codebase

Start new work in TypeScript while keeping existing JavaScript modules intact.
Annotate critical JS with JSDoc so TypeScript can infer types when checkJs is enabled.
Use ambient declarations to describe legacy libraries without typings.
Import JS modules in TS using standard ESModule syntax, and switch to TS imports when ready.
Centralize shared types in a dedicatedDeclarations file to enforce consistency across both languages.
Consider enabling isolatedModules in TS to catch cross file issues during incremental migration.

Migration strategies for teams

Plan by domain, not by file type. Identify high-value modules that provide the biggest payoff from typing and convert them first. Maintain regression tests and run TS builds alongside your existing JS tests to catch integration issues early. Use wrappers around untyped code to provide a stable typing surface while you migrate. Keep typings as an evolving artifact, updating references as libraries evolve. This staged approach minimizes risk and preserves shipping velocity.

Common pitfalls and how to avoid them

Watch for inconsistencies at the JS and TS boundary, such as mismatched function signatures or implicit any types. Avoid over-annotating small, simple helpers that do not benefit much from typing. Be mindful of libraries without typings and provide ambient declarations or keep using JS wrappers until typings exist. Regularly review tsconfig settings to ensure they align with project structure and build tooling. A clear governance around typings helps teams stay productive without sacrificing safety.

Getting started: a minimal setup

To begin a hybrid project, create a TypeScript configuration that allows JavaScript and, optionally, checks JavaScript. Place existing code under a common src folder and start with a few TS files that import a couple of JS modules. Install TypeScript and typings for common libraries as dev dependencies, then run the compiler to see errors and fix gradually. Over time, you can convert more modules to TS and reduce JS usage. This approach keeps momentum while delivering incremental safety gains without a full rewrite.

Quick reference: settings and tips

enable allowJs to permit JS files in the TS project
enable checkJs to type-check JavaScript when needed
keep a central place for type declarations used by both languages
prefer .ts/.tsx for new development; reserve .js for legacy code
use JSDoc to annotate JS for better type inference
regularly verify builds with both TS and JS tests

Questions & Answers

Can you mix JavaScript and TypeScript in the same project?

Yes. You can enable interop by configuring tsconfig with allowJs and optional checkJs. Start with a few modules and gradually expand typing coverage as you migrate. This approach minimizes risk while delivering safety gains.

Do I need to rename all files to ts or tsx to start using TypeScript?

No. With allowJs you can keep existing .js files and progressively add .ts or .tsx files. Rename when you are ready, prioritizing modules with high value or risk reduction.

Is type checking possible for JavaScript files?

Yes, if you enable checkJs and provide JSDoc types or ambient declarations. This helps catch issues in JS code without rewriting it all in TypeScript.

How should I migrate code without breaking the app?

Start with high-value modules, run tests continually, and introduce type-safe wrappers for untyped code. Move modules gradually and verify behavior at each step.

What about libraries that do not have typings?

Add ambient declarations or declare module types in a d.ts file, or install available @types packages if they exist. This keeps JS libraries usable in TS code without breaking builds.