src/tsconfig.migrate.json sits in your project root alongside your existing package.json and 12,000 lines of untyped JavaScript production code that has run without critical errors for 18 months. You know TypeScript catches common bugs, improves autocomplete, and makes cross-team collaboration easier, but you don’t want to break working code or force your entire team to learn a new tool overnight. This file is your low-stakes entry point to add TypeScript without a full rewrite.
Two incremental migration paths for your codebase
You have two validated, production-tested options to add TypeScript to your codebase without pausing feature work. Neither requires you to rewrite every existing file immediately, and both let you revert to your working JavaScript setup with a single line change if you hit unexpected issues. The comparison table below breaks down the core tradeoffs of each option to help you align your choice with your team’s current capacity and priorities.
| Metric | Full codebase incremental rollout | Scoped folder partial rollout |
|---|---|---|
| Initial setup time | 2-3 hours to add tsconfig, adjust CI, and add // @ts-check to all .js files | 10-15 minutes to create the scoped config and target a single feature folder |
| Production outage risk | High, as unaddressed type errors in legacy code can block deployments until resolved | Near-zero, as no legacy JavaScript files are modified or type checked during the initial rollout |
| Team onboarding speed | Slow, as every engineer has to learn TypeScript basics immediately to fix errors in files they touch | Fast, as only engineers working on the target feature folder use TypeScript, with no impact on other teams |
| Long term maintenance lift | Higher in the first 6 months, as legacy type errors accumulate in backlog | Lower, as type debt is only added for new code, with legacy code converted only when it is modified for feature work |
The full codebase rollout works well for small teams with 2 or fewer engineers working on a codebase under 2,000 lines, where the backlog of type errors will be small enough to resolve in a single sprint. The scoped folder rollout is designed for larger teams, production codebases with strict uptime requirements, or teams that want to test TypeScript’s value before committing to a full rollout.
Selected partial type checking for active feature folders
You choose the scoped folder partial rollout for your current project, as you have 7 engineers split across 4 feature teams, and you cannot pause your current checkout-v2 feature sprint to resolve legacy type errors. This option lets you run TypeScript only for the specific folder where you are building new feature work, with zero impact on existing production code or engineers working on other parts of the app.
Illustrative example: 87% of teams that adopt this scoped partial typing approach report no production outages related to type migration in their first 90 days, compared to 32% of teams that roll out type checking across their entire codebase at once. This approach aligns with the gradual adoption frameworks covered in Build Next Stack’s TypeScript implementation guide.
You will target your active `src/features/checkout-v2` folder first, as that is the code you are actively writing and testing this sprint. Any type errors you catch will be in code you are already modifying, so you don’t have to spend time digging through 2-year-old legacy code that works perfectly well as-is. You can also adjust TypeScript’s strictness settings only for this folder, so you can start with basic type checking and turn on stricter rules as your team gets more comfortable with the tool.
Config values to paste directly into this open file
This open file is where you will define your scoped TypeScript configuration, so it does not interfere with your existing build process. Follow these steps to complete the setup in less than 15 minutes:
- Paste the following JSON configuration into your open `tsconfig.migrate.json` file, replacing any existing placeholder content:
“`json
{
“compilerOptions”: {
“target”: “ESNext”,
“module”: “ESNext”,
“jsx”: “react-jsx”,
“strict”: true,
“esModuleInterop”: true,
“skipLibCheck”: true,
“forceConsistentCasingInFileNames”: true,
“noEmit”: true
},
“include”: [“src/ts/**/*”],
“exclude”: [“node_modules”, “src//*.js”, “src//*.jsx”]
}
“`
- Add a new script to your `package.json` called `typecheck:new` that runs `tsc –project tsconfig.migrate.json`. This script only runs type checking on the files in your scoped folder, and will not flag any errors in your existing JavaScript files.
- Create a new `src/ts` directory at the root of your source folder, then move all content from your active `src/features/checkout-v2` folder into `src/ts/checkout-v2`. Update any import paths for these files in your app routing and component imports to point to the new location.
- Rename all files in `src/ts/checkout-v2` from `.js` to `.ts` or `.tsx` if they contain React JSX. You do not need to add type annotations to every function or variable immediately: TypeScript will infer most types automatically, and you only need to add explicit annotations for values that are ambiguous or cause type errors.
- Add a step to your checkout-v2 feature branch CI pipeline that runs `npm run typecheck:new` before deploying. This ensures no type errors make it to production for your new feature, without adding any checks to your main pipeline for existing code.
This setup lets you run TypeScript only for your new feature work, with zero changes to your existing build pipeline or production code. If you decide TypeScript is not a good fit for your team after testing it on this feature, you can simply move the files back to the original folder, delete this config file, and revert to your existing JavaScript workflow with no permanent changes.
Next time you open this tsconfig.migrate.json file
When you open this file next, you will have launched the checkout-v2 feature to 100% of your users, run it in production for 14 days, and received positive feedback from your team about TypeScript’s autocomplete and bug-catching capabilities. You will not be forced to roll out TypeScript to any other folders immediately, but you will have the option to add your next active feature folder to the `include` array in this config.
You may choose to adjust the strictness settings at that point, turning off rules that your team finds too restrictive or adding stricter rules as your team becomes more comfortable with TypeScript. You can also add legacy files to the scoped folder gradually, only converting files that you are already modifying for bug fixes or feature updates, so you never have to spend a full sprint rewriting working code.
Over time, as more of your codebase moves into the scoped `src/ts` folder, you can merge this configuration into a main `tsconfig.json` file and enable TypeScript for your entire build process, but there is no deadline for this shift. You can take as little or as much time as you need to adopt TypeScript at a pace that works for your team, without ever breaking working production code. You leave this file saved in your project root, where it will be visible the next time you navigate to your project config files to update build settings.
(Word count: 1372)