Skip to content
Muhammet Şafak
tr
Languages 3 min read

Migrating to TypeScript: Type Safety in JavaScript

My practical experience adopting TypeScript in a growing frontend codebase — what I gained, what I lost, and when it actually proved its worth.

A clipped stack of legacy app.js pages at left, and a violet-lit grid of cubes for interface, type and extends at right

Written 7 years ago — it reflects the conditions of that time.


As my frontend codebases grew, I kept noticing the same pattern: passing the wrong type to a function parameter, reading a non-existent property — these mistakes surfaced at runtime, often far too late. When I adopted stricter type declarations in PHP 7.x, the confidence it gave me was significant. I wanted the same guarantee on the JavaScript side. By the time I decided to migrate to TypeScript, I felt prepared — but the real experience turned out different from what I expected.

What is TypeScript?

TypeScript is a superset of JavaScript developed by Microsoft that adds a static type system to the language. The TypeScript code you write compiles down to plain JavaScript — no special runtime is needed for the browser or Node.js. TypeScript’s job is to tell you at write time: “this value expects a string, but you’re passing a number.”

Where I started the migration

The least painful way to add TypeScript to an existing project is to start with "strict": false in tsconfig.json and tighten things up gradually. You don’t have to rename every file from .js to .ts; with allowJs: true you can mix both formats freely.

When I decided to write a new component, I started it directly in TypeScript:

interface User {
  id: number;
  name: string;
  email: string;
  role: 'admin' | 'editor' | 'viewer';
}

function formatUserLabel(user: User): string {
  return `${user.name} <${user.email}>`;
}

// This line produces a compile-time error:
// formatUserLabel({ id: 1, name: 'Test' }); // email is missing

In PHP, type declarations live in method signatures; in TypeScript you define the shapes of your data using interfaces or type aliases. It felt a bit strange at first, but I got used to it quickly.

When it proved most valuable

Refactoring confidence. When you rename a field on an interface, TypeScript flags every place that uses it. In plain JavaScript, you would only discover that mistake at runtime — or if your tests happened to catch it.

IDE integration. Autocomplete becomes dramatically more useful with TypeScript. Type user. and the editor already knows which fields exist. Pass the wrong type to a parameter and you get a red underline immediately.

Team communication. Interfaces act as living documentation — they make it explicit what a function expects and what it returns.

Points of friction

TypeScript’s learning curve comes less from the syntax and more from the type system itself. Simple cases are easy to express. But in the real world:

// When the response type from an external API is unknown:
const response = await fetch('/api/users');
const data = await response.json(); // 'any' type — no guarantees

Bringing external data into the type system requires type guards or as type assertions. This is still an area where I’m learning.

function isUser(obj: unknown): obj is User {
  return typeof obj === 'object' && obj !== null && 'id' in obj;
}

Also, not every third-party library ships with TypeScript types. The @types/... packages cover most popular libraries, but you sometimes have no choice but to work with any.

strict mode: enable it early or late?

Starting with "strict": false makes the migration easier, but there’s a trap: with strict off, TypeScript may not protect you from real bugs either. Without strictNullChecks, nullable errors go undetected; without noImplicitAny, the any type spreads silently. Turning on strict: true in new files from the very beginning was far less painful than trying to expand coverage later. Gradually tightening the old files is a separate effort — but it is doable.

Abandoning JavaScript?

TypeScript is not an alternative to JavaScript; it sits on top of it. All your existing JavaScript is valid TypeScript. The difference is this: TypeScript doesn’t slow you down — it actually lets you move faster in large codebases. For a small throwaway script, type declarations may be overkill; but for a multi-developer project with hundreds of files, the trade-off clearly favors TypeScript.

I now get the same comfort on the frontend that type safety has always given me in my PHP backend. There is an upfront cost to the migration, but over the long run it is worth it.

Frequently asked

6 questions

  • What is TypeScript?

    TypeScript is a superset of JavaScript developed by Microsoft that adds a static type system to the language. The code you write compiles down to plain JavaScript, so no special runtime is needed for the browser or Node.js. Its job is to tell you at write time that a value expects a string but you are passing a number.

  • How do you start migrating an existing project?

    The least painful way is to start with strict set to false in tsconfig.json and tighten things gradually. You do not have to rename every file from .js to .ts, because with allowJs set to true you can mix both formats freely. For new components I started directly in TypeScript.

  • When does TypeScript prove most valuable?

    In refactoring, where renaming a field on an interface flags every place that uses it; in the IDE, where autocomplete knows which fields exist; and in team communication, where interfaces act as living documentation of what a function expects and returns.

  • Should you enable strict mode early or late?

    Early, at least in new files. With strict off, TypeScript may not protect you from real bugs: without strictNullChecks nullable errors go undetected, and without noImplicitAny the any type spreads silently. Turning strict on in new files from the beginning was far less painful than expanding coverage later. Tightening the old files is a separate effort, but it is doable.

  • What causes friction when adopting TypeScript?

    The learning curve comes less from the syntax and more from the type system itself. Data from an external API arrives as any, so bringing it into the type system needs type guards or as assertions. Not every third-party library ships types either, so you sometimes have no choice but to work with any.

  • Does TypeScript replace JavaScript?

    No, it sits on top of it, and all your existing JavaScript is valid TypeScript. For a small throwaway script type declarations may be overkill, but for a multi-developer project with hundreds of files the trade-off clearly favors TypeScript.

Experiments on this topic

Build notes on a dice-free 4X core of 480 hexes and at most 60 turns, offline in the browser: a constraint chose the scope, and it shipped as Regnarium.

What it does today

Runs a full 4X match on a 480-hex map in at most 60 turns; rules, map generation and the opponent AI live in one pure TypeScript core, and combat rolls no dice. Anyone with half an hour and an appetite for strategy can open it in a browser.

Web TypeScript Next.js React +2 more
September 2026 — September 2026

A desktop app that reads Claude Code, Codex CLI and Gemini CLI logs locally and shows token usage by project, model and session.

What it does today

Collects AI agent token usage from local logs and shows it by project, model, session and time, with estimated cost and subscription limit tracking. A developer who uses Claude Code, Codex CLI or Gemini CLI heavily and wants to see the spend can install it.

Open-Source Desktop Go Wails Svelte +2 more
November 2026 — Ongoing

Comments

Sign in with your GitHub account to join the discussion. Comments are stored in GitHub Discussions.

Related Posts

Search the site

Start typing to search posts, projects and pages.

Esc to close Powered by Pagefind