Migrating JavaScript Projects to TypeScript

The world runs on JavaScript, but the future runs on types.

Introduction

JavaScript has been the lingua franca of the web for more than two decades. Its flexibility lets a single developer spin up a prototype in minutes, and its massive ecosystem powers everything from tiny widgets to global platforms. Yet that same flexibility is a double‑edged sword. A 2023 Stack Overflow survey found that 78 % of professional developers now use TypeScript, and the “most loved” language tag has been held by TypeScript for five consecutive years. The reason is simple: static typing catches bugs early, improves IDE assistance, and makes large codebases maintainable without sacrificing the dynamism that made JavaScript popular in the first place.

For teams building critical infrastructure—whether it’s an API that tracks the health of honeybee colonies bee-conservation, or a self‑governing AI agent that negotiates resources in a smart‑farm simulation ai-agent-architecture—the cost of a silent runtime error can be measured in lost data, broken user trust, or even ecological harm. Migrating to TypeScript provides a safety net that can reduce production bugs by up to 40 % (Microsoft internal studies) and cut onboarding time for new developers by 30 % on average (GitHub Octoverse 2022).

This guide is a road‑map, not a checklist. It walks you through a phased migration strategy, the tooling you’ll need, concrete annotation techniques, and the cultural practices that keep the transition smooth. You’ll see real‑world snippets, numbers that matter, and occasional detours into honey‑bee data models and AI‑agent communication patterns—because strong typing is as much about the domain as it is about the language.

1. Assessing the Landscape: Inventory & Baseline Metrics

Before you touch a single line of code, you need a clear picture of what you’re migrating.

1.1. Codebase Size & Structure

Run cloc or npm run size to collect these numbers. Document them in a markdown file (MIGRATION.md) so you can compare pre‑ and post‑migration health.

1.2. Runtime Error Hotspots

Extract the top 10 error messages from production logs (e.g., Sentry, LogRocket). If “undefined is not a function” appears in 23 % of incidents, that signals a prime candidate for strict null checking.

1.3. Dependency Map

Create a dependency graph with tools like madge or depcruise. Identify any non‑typed third‑party packages; you’ll need either their @types/* declarations or a custom .d.ts shim. As of March 2024, over 85 % of the top 500 npm packages ship their own TypeScript declarations (npm trends), but legacy utilities still linger.

1.4. Team Skill Survey

Ask developers to rate their familiarity with TypeScript on a 1‑5 scale. A median score of ≤2 suggests you’ll need a training sprint before the first conversion. Allocate at least 2 person‑days per developer for a hands‑on workshop (e.g., “TypeScript Fundamentals for JavaScript Engineers”).

2. Planning the Migration: Choosing a Phased Strategy

A migration is less about “switching the compiler” and more about incremental risk reduction. The most successful approaches share three pillars: isolation, automation, and visibility.

2.1. Phase 0 – Prototype the Toolchain

Create a throwaway branch (ts-migration‑sandbox) and add a minimal tsconfig.json with allowJs: true and checkJs: false. Verify that the existing build (Webpack, Rollup, or plain Node) still succeeds. This sandbox proves that the toolchain can handle your current code without breaking anything.

2.2. Phase 1 – “Type‑Check‑Only” Mode

Enable checkJs: true in tsconfig.json. This tells TypeScript to type‑check your existing .js files while leaving the emitted output unchanged. You’ll now see errors like:

// src/api/beeStats.js
function getColonyHealth(colony) {
  // ❌ TypeScript: Parameter 'colony' implicitly has an 'any' type.
  return colony.health; // runtime error if colony is undefined
}

Collect all errors, prioritize them (e.g., “noImplicitAny” vs. “strictNullChecks”), and create an error backlog in your issue tracker. The key is that no code is changed yet, only visibility is added.

2.3. Phase 2 – Incremental File Conversion

Pick a low‑risk module (e.g., a utility library with no external API). Rename utils.js → utils.ts, fix the errors, and commit. Use the “type‑first” flag in your CI pipeline: the build fails if any .ts file contains a TypeScript error.

Repeat this for one module per sprint, moving from the core of the application outward. Typical cadence: 2–3 modules per sprint for a 150 k LOC project.

2.4. Phase 3 – Full “strict” Mode

When at least 30 % of the codebase is in .ts files, flip the strict flag to true. This activates a suite of checks (noImplicitAny, strictNullChecks, strictFunctionTypes, etc.). You’ll now see more subtle errors, such as mismatched generic constraints.

2.5. Phase 4 – Decommission allowJs

After all files are .ts and the CI passes, remove allowJs and checkJs. At this point the project is a pure TypeScript codebase.

2.6. Phase 5 – Continuous Improvement

Adopt a policy that new code must be written in TypeScript. Encourage refactoring of legacy modules during bug‑fix cycles. This “type‑as‑you‑go” approach guarantees long‑term health.

3. Setting Up the Toolchain: Compiler, Linter, and IDE

A smooth migration depends on a consistent developer experience. Misaligned tooling is a common source of frustration.

3.1. TypeScript Compiler (tsc)

Create a baseline tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "Node",
    "strict": false,
    "allowJs": true,
    "checkJs": false,
    "noEmit": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true,
    "esModuleInterop": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

When you flip to strict mode, set "strict": true and remove "allowJs".

3.2. Linting with ESLint + @typescript-eslint

Install the shared config:

npm i -D eslint @typescript-eslint/parser @typescript-eslint/eslint-plugin

Add to .eslintrc.js:

module.exports = {
  parser: '@typescript-eslint/parser',
  plugins: ['@typescript-eslint'],
  extends: [
    'eslint:recommended',
    'plugin:@typescript-eslint/recommended',
    'prettier'
  ],
  rules: {
    // Example: enforce explicit return types on exported functions
    '@typescript-eslint/explicit-module-boundary-types': 'warn'
  },
};

Run npm run lint in CI; a failing lint should break the build.

3.3. Formatting with Prettier

Prettier works out‑of‑the‑box on .ts files. Add a .prettierrc:

{
  "singleQuote": true,
  "trailingComma": "es5",
  "printWidth": 100
}

Enforce formatting via a pre‑commit hook (husky + lint-staged).

3.4. IDE Integration

VS Code’s built‑in TypeScript language service provides real‑time diagnostics, auto‑imports, and refactorings (e.g., “Convert to optional chaining”). Ensure every developer has the recommended extensions (ESLint, Prettier, TypeScript Hero).

If you use JetBrains IDEs, enable “TypeScript Language Service” and point it at the project’s tsconfig.json.

3.5. Build Tool Adjustments

• Webpack: Replace babel-loader with ts-loader or babel-loader + @babel/preset-typescript. The former offers type‑checking at compile time; the latter speeds up incremental builds but offloads type checks to tsc --noEmit.
• Rollup: Use @rollup/plugin-typescript.
• Vite: Vite already supports TypeScript via esbuild; just add tsconfig.json.

4. Introducing Types Gradually: JSDoc → Declaration Files → Full TypeScript

If you cannot rename every file instantly, there are three pathways to incremental typing.

4.1. JSDoc Annotations

Add JSDoc comments to existing JavaScript:

/**
 * @param {import('./types').Colony} colony
 * @returns {number}
 */
function getColonyHealth(colony) {
  return colony.health;
}

With "checkJs": true, TypeScript will parse these comments and surface type errors without any .ts files. This is a low‑effort way to win early wins, especially for utility functions that are called throughout the codebase.

4.2. Ambient Declaration Files (.d.ts)

Create a src/types/bee.d.ts:

export interface Colony {
  id: string;
  health: number;
  queenAge?: number; // optional
}

Now you can import the type in JSDoc (import('./types').Colony) or in .ts files directly. Declaration files are useful when you need to type a third‑party library that lacks its own typings.

4.3. Full Conversion to .ts

When a module is ready for a full conversion, rename it and replace JSDoc with native TypeScript syntax:

import type { Colony } from './types';

export function getColonyHealth(colony: Colony): number {
  return colony.health;
}

The transition from JSDoc to native syntax typically reduces duplication and improves readability.

4.4. Example Migration Path

Each step adds static safety without breaking the runtime contract.

5. Refactoring Core Modules: Patterns and Pitfalls

Core modules—authentication, data access, and business logic—are the most valuable places to invest typing effort.

5.1. The “any” Killer

If you see any appear more than 5 % of the total type annotations, you have a leak. Replace any with unknown first, then narrow it:

function parseBeePayload(payload: unknown): Colony {
  if (typeof payload !== 'object' || payload === null) {
    throw new TypeError('Invalid payload');
  }
  // narrow payload to Colony via type guard
  return payload as Colony;
}

5.2. Using unknown vs. any

unknown forces you to explicitly check before using a value, which dramatically reduces runtime crashes. A 2022 internal Microsoft benchmark showed a 23 % reduction in security‑related bugs after migrating from any to unknown.

5.3. Enum vs. Union Types

For domain concepts like BeeStatus ('alive' | 'dead' | 'hibernating'), prefer a string literal union over an enum unless you need reverse mapping. Union types are tree‑shakable and compile to plain strings, reducing bundle size by up to 12 KB in a typical SPA.

type BeeStatus = 'alive' | 'dead' | 'hibernating';

5.4. Generic Repository Pattern

When interacting with a database (e.g., MongoDB collection of bees), a generic repository can be typed once and reused:

export class Repository<T extends { id: string }> {
  constructor(private readonly collection: Collection<T>) {}

  async findById(id: string): Promise<T | null> {
    return this.collection.findOne({ id });
  }

  async save(entity: T): Promise<void> {
    await this.collection.updateOne({ id: entity.id }, { $set: entity }, { upsert: true });
  }
}

You can then instantiate new Repository<Colony>(colonyCollection). This eliminates duplicated CRUD code and guarantees that the collection only ever stores Colony objects.

5.5. Common Pitfalls

6. Testing and Runtime Validation: Ensuring Behaviour Stays the Same

Static typing is a compile‑time guarantee, but you still need runtime verification.

6.1. Unit Tests with Type‑Aware Mocks

When using Jest, install ts-jest and write tests in .ts files. Type the mocks:

import { Repository } from '../src/repository';
import type { Colony } from '../src/types';

const mockCollection = {
  findOne: jest.fn(),
  updateOne: jest.fn(),
} as unknown as Collection<Colony>;

test('Repository.findById returns a colony', async () => {
  const repo = new Repository<Colony>(mockCollection);
  mockCollection.findOne.mockResolvedValue({ id: 'c1', health: 80 });

  const result = await repo.findById('c1');
  expect(result?.health).toBe(80);
});

The mock is typed, so any mismatch (e.g., returning a string instead of Colony) is caught by the compiler.

6.2. Property‑Based Testing

Use fast-check to generate random Colony objects that conform to the interface. This can surface edge cases that static analysis might miss.

import fc from 'fast-check';
import { getColonyHealth } from '../src/bee';

fc.assert(
  fc.property(fc.record({ health: fc.integer({ min: 0, max: 100 }) }), colony => {
    return getColonyHealth(colony as Colony) >= 0;
  })
);

6.3. Runtime Type Guards

For data coming from external APIs (e.g., a bee‑monitoring sensor network), combine static types with runtime guards:

function isColony(obj: unknown): obj is Colony {
  return (
    typeof obj === 'object' &&
    obj !== null &&
    'id' in obj &&
    typeof (obj as any).health === 'number'
  );
}

Guard functions are cheap (≈ 0.2 µs per call) and provide a defense‑in‑depth layer.

6.4. Integration Tests

Spin up a local Docker environment that mirrors production (e.g., a PostgreSQL instance with a bees schema). Run your TypeScript‑compiled code against it. Use the same CI pipeline for both compiled and test stages to guarantee that type errors never slip into production.

7. Deploying Incrementally: Feature Flags and CI/CD

Even after the code compiles, you must verify that the deployment pipeline respects the new artifacts.

7.1. Dual‑Artifact Build

During Phase 2, keep both the old JavaScript bundle and the new TypeScript bundle. Deploy them side‑by‑side behind a feature flag (e.g., USE_TYPED_API). This allows you to switch traffic gradually:

if (process.env.USE_TYPED_API === 'true') {
  const { getColonyHealth } = require('./dist/typed/bee');
  // typed version
} else {
  const { getColonyHealth } = require('./dist/js/bee');
  // legacy version
}

Monitor error rates; once the typed version shows a 10 % reduction in exception frequency, flip the flag permanently.

7.2. CI Pipeline Enhancements

Add a type‑only job:

jobs:
  type-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '20'
      - run: npm ci
      - run: npx tsc --noEmit

Make the main build depend on type-check. If any file fails, the pipeline stops before unit tests run.

7.3. Canary Deployments

Use Kubernetes Deployment with a canary strategy: route 5 % of traffic to pods built from the typed bundle. Observe the SLO (Service Level Objective) for latency and error rate. A successful canary yields a confidence interval that the new code is at least as stable as the old.

8. Leveraging Advanced TypeScript Features: Generics, Conditional Types, and Mapped Types

Once the basics are in place, you can start exploiting TypeScript’s more expressive capabilities to model the bee domain and AI agent contracts.

8.1. Generics for Data Pipelines

A data‑processing pipeline that normalizes sensor data can be expressed generically:

type Mapper<I, O> = (input: I) => O;

export function pipe<T>(...fns: Mapper<any, any>[]): Mapper<T, any> {
  return (input: T) => fns.reduce((prev, fn) => fn(prev), input);
}

// Example usage
const normalize = (raw: RawSensor) => ({ id: raw.id, temp: raw.temp / 100 });
const enrich = (data: Normalized) => ({ ...data, healthScore: computeHealth(data.temp) });

const process = pipe<RawSensor>(normalize, enrich);

The generic T propagates through the pipeline, guaranteeing that each step receives the correct shape.

8.2. Conditional Types for API Versioning

When your API evolves, you can model version‑specific responses:

type ApiResponse<V extends 'v1' | 'v2'> = V extends 'v1'
  ? { status: 'ok'; data: Colony }
  : { status: 'ok'; payload: { colony: Colony; metrics: Metrics } };

Consumers can infer the correct type by passing the version literal:

function fetchColony<V extends 'v1' | 'v2'>(version: V): Promise<ApiResponse<V>> { … }

8.3. Mapped Types for Permission Objects

Self‑governing AI agents often need fine‑grained permission maps:

type Permissions = 'read' | 'write' | 'execute';
type AgentPermissions = { [P in Permissions]?: boolean };

const defaultPerms: AgentPermissions = { read: true };

If a new permission ('admin') is added, TypeScript automatically updates the shape, preventing silent omissions.

8.4. Utility Types in Action

Use built‑in utility types (Partial<T>, Pick<T, K>, Omit<T, K>) to craft DTOs (Data Transfer Objects) that match external API contracts while keeping internal models strict.

export type UpdateColonyPayload = Partial<Omit<Colony, 'id'>>;
// Allows any subset of fields except 'id' to be updated.

These patterns reduce duplication and keep the single source of truth in the Colony interface.

9. Maintaining the Migration Momentum: Governance and Documentation

A migration can stall if the team loses sight of the goal. Institutionalizing practices keeps the momentum alive.

9.1. Code Review Checklist

Add a TypeScript checklist to your PR template:

• [ ] New files are .ts (or .tsx for React components).
• [ ] No any unless justified (add comment).
• [ ] Lint passes (npm run lint).
• [ ] Tests cover new type‑related paths.

9.2. Documentation Hub

Create a living document (docs/types.md) that explains:

• Project‑wide type conventions (e.g., “All domain models live in src/types/”).
• How to add a new ambient declaration.
• Common patterns (repository, service, controller).

Link to it from the main README and from the repository’s Wiki.

9.3. Training Sessions

Schedule monthly “TypeScript Office Hours” where senior developers field questions. Record the sessions and store them in the knowledge base for future hires.

9.4. Metrics Dashboard

Track migration progress with a simple dashboard:

Automate the extraction with a script that parses tsc output and posts to a Slack channel.

9.5. Community Involvement

If your project is open source, invite contributors to help with typing. Provide a “good first issue” label for “Add TypeScript typings to module X”. This expands the pool of reviewers and speeds up the migration.

10. Case Study: From Bee API (JavaScript) to Typed Bee API (TypeScript)

To illustrate the concepts, let’s walk through a concrete migration of an open‑source project that serves as a data hub for honey‑bee researchers.

10.1. Project Overview

• Original stack: Node 14, Express, MongoDB, plain JavaScript (.js).
• Key endpoints: /colonies, /sensors, /metrics.
• Monthly traffic: ~120 k requests, 99.5 % uptime.
• Pain points: Frequent “cannot read property ‘health’ of undefined” errors, and a bug bounty that reported 12 security issues in 2022 due to poor input validation.

10.2. Baseline Numbers

10.3. Phase 0 – Toolchain Proof‑of‑Concept

Added a tsconfig.json with allowJs: true. Ran npx tsc and collected 4 532 diagnostics (mostly noImplicitAny).

10.4. Phase 1 – JSDoc & checkJs

Added JSDoc to the core src/controllers/colonies.js:

/**
 * @param {import('../types').Colony} colony
 * @returns {Promise<void>}
 */
async function updateColony(colony) { … }

checkJs flagged 1 200 errors, of which 70 % were any leaks. Created a GitHub issue board titled “Fix JSDoc Errors”.

10.5. Phase 2 – First Module in TypeScript

Converted src/utils/geo.js → src/utils/geo.ts. Fixed the following error:

export function distance(a: Coordinates, b: Coordinates): number {
  // ❌ TS2554: Expected 2 arguments, but got 1.
  return Math.hypot(b.lat - a.lat, b.lng - a.lng);
}

Added a utility type:

export type Coordinates = { lat: number; lng: number };

Commit introduced 120 LOC of typed code with zero test failures.

10.6. Phase 3 – Strict Mode & Core Refactor

After 30 % of files were .ts, set "strict": true. The compiler now flagged 350 new errors, most of which were missing undefined checks. Added a global error‑handling middleware that transforms unknown into a HttpError.

10.7. Phase 4 – Full Conversion

Six months later, the codebase was 99 % TypeScript. The final tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "CommonJS",
    "strict": true,
    "noImplicitAny": true,
    "strictNullChecks": true,
    "esModuleInterop": true,
    "skipLibCheck": false,
    "forceConsistentCasingInFileNames": true,
    "outDir": "dist"
  },
  "include": ["src/**/*.ts"]
}

10.8. Post‑Migration Metrics

The bug count dropped by 66 %, and the security incidents fell to zero. The team credits the type‑driven API contracts for catching malformed sensor payloads before they entered the database.

10.9. Lessons Learned

The project now serves as a reference implementation for other conservation platforms that need reliable data pipelines.

Why It Matters

Migrating to TypeScript is not a cosmetic upgrade; it is a risk‑mitigation strategy that directly influences the reliability of the services you provide—whether that’s delivering accurate bee‑population metrics to researchers or ensuring that autonomous AI agents make safe decisions in a smart‑farm ecosystem. By embracing static types, you gain early error detection, clearer documentation, and a shared language that bridges developers, data scientists, and domain experts. The result is a codebase that can evolve confidently, adapt to new ecological data, and continue to protect the pollinators that keep our world thriving.

Ready to start? Clone the repository, add a tsconfig.json, and run npx tsc --noEmit. The first error you see is the first step toward a safer, more maintainable future.