The Bottom-Up vs Top-Down Decision
You'll learn: How to choose whether to start migrating utility functions first (bottom-up) or entry points first (top-down) based on your project's structure.
Two Migration Paths
When gradually migrating JavaScript to TypeScript, you face a strategic choice: where to begin? This decision significantly impacts your migration experience.
Bottom-up migration means starting with low-level utility functions and data structures that other parts of your code depend on. You convert leaf nodes in your dependency tree first, then work upward toward entry points.
Top-down migration means starting with entry points like main.ts, route handlers, or application controllers. You convert the outer layers first, using type stubs or any for deeper dependencies, then progressively type deeper modules.
The Bottom-Up Case
Think of bottom-up like building a house from the foundation. You establish type-safe utilities first:
- Predictable dependencies: Utilities typically have fewer dependencies themselves
- Reusable safety: Once typed, many files benefit immediately
- Gradual strictness: You can enable strict mode in typed files while allowing loose checking elsewhere
- Better for shared libraries: If multiple parts of your codebase use common helpers, typing them creates widespread benefit
Best for: Projects with well-defined utility layers, shared function libraries, or when you want maximum type coverage in foundational code before moving up.
The Top-Down Case
Top-down is like renovating a house room by room. You fix what users see first:
- Immediate user impact: Entry points are where bugs hurt most
- Guided by usage: You discover which types matter based on actual application flow
- Less upfront work: You only type what the application actively uses
- Natural boundaries: Application layers often align with migration phases
Best for: Monolithic applications with unclear dependency hierarchies, rapidly changing codebases where priorities shift, or when you want type safety at critical touch points first.
Making Your Choice
Consider your project structure. If src/utils/ is used everywhere, bottom-up makes sense. If you have distinct feature folders with clear entry points, top-down may flow naturally. Many teams blend both: entry points top-down while simultaneously typing common utilities bottom-up.
Key Takeaway: Bottom-up builds type safety from shared foundations outward, while top-down secures critical paths first—choose based on your dependency structure and where bugs hurt most.