Migrating Large TypeScript Codebases To Project References

Summary

Shopify’s merchant admin UI grew from a Ruby on Rails ERB-based front-end into a TypeScript, React, and GraphQL codebase, and its size eventually made VSCode’s TypeScript language tooling take roughly two to three minutes to initialize. The team investigated the bottleneck with TypeScript’s performance diagnostics, VSCode TSServer logs, and support from the TypeScript team, which recommended splitting the monolithic configuration with project references. They built the TypeTrack VSCode plugin to measure initialization time, then migrated dependency-graph leaf nodes such as packages and tests, creating project-level tsconfig.json files and references incrementally. The migration reduced initialization times for sampled files from about 155 seconds to 8–13 seconds. The post explains how to resolve missing module errors, respect project-reference restrictions, and continue upward through the dependency graph while distributing migration work across teams.

Context

The Shopify merchant admin UI had grown into one of the largest TypeScript codebases encountered by the TypeScript team. Its single TypeScript configuration taxed VSCode’s language tooling, causing initialization to take roughly two to three minutes and creating a frustrating development experience for teams shipping commerce features.

Approach / What changed

The migration uses TypeScript project references to divide the codebase into smaller projects. Teams begin with leaf nodes such as packages and tests, create project-level tsconfig.json files, add dependency references, run the compiler with diagnostics, fix errors, and move upward through the dependency graph. Shopify also created the TypeTrack VSCode plugin to measure editor initialization times.

Takeaways

• TypeScript project references let VSCode’s TS Server load only the files required by the project containing an opened file instead of the entire codebase.
• Shopify reduced sampled VSCode TypeScript initialization times from about 155 seconds to 8–13 seconds after migrating packages and tests.
• Project-reference migrations must respect include/files coverage, references arrays, and configured paths for locally imported namespaces.

Related reading