TypeScript: When to Use It (And When Plain JS is Enough)

Every few months, someone on my team suggests converting a project to TypeScript. "It'll catch bugs!" "It's the future!" "Everyone's doing it!"

They're not wrong. TypeScript is genuinely useful. But they're also not entirely right. After converting over 10 projects—some successfully, some not—I've developed a framework for when TypeScript actually helps versus when it's just adding ceremony.

Here's what I've learned.

What TypeScript Actually Gives You

Let's be honest about what TypeScript does and doesn't do:

What It Does Well

• Catches type mismatches at compile time - No more "undefined is not a function" in production
• Enables better IDE support - Autocomplete that actually works, inline documentation, refactoring tools
• Documents your code - Types ARE documentation that stays current
• Makes refactoring safer - Change a type, see everywhere that breaks

What It Doesn't Do

• Catch logic errors - Your algorithm can be perfectly typed and completely wrong
• Replace tests - Types check structure, tests check behavior
• Guarantee runtime safety - External data (APIs, user input) can still break things
• Make bad code good - Typed spaghetti is still spaghetti

When TypeScript Is Worth It

1. Large Codebases (10,000+ Lines)

In small projects, you can keep the whole codebase in your head. In large projects, you can't. Types become essential documentation.

Without types, you're constantly asking: "What shape is this data? What does this function return? Can this be null?" With types, the answer is always in front of you.

2. Multiple Contributors

Solo developer? You know your own conventions. Team of five? Everyone has different assumptions about data shapes, null handling, and function signatures.

Types enforce contracts between developers. They're like automated code review for data shapes.

3. Long-Lived Projects

If your project will be maintained for years, TypeScript is almost always worth it. Future you (or future maintainers) will thank present you.

I've returned to untyped projects after 6 months and spent hours reverse-engineering what I meant. TypeScript projects? The types tell me immediately.

4. Complex Data Transformations

If your code does a lot of data manipulation—transforming API responses, aggregating data, converting between formats—types prevent entire categories of bugs.

// Without types: hope this works
const users = response.data.map(u => ({
  fullName: u.first + ' ' + u.last,
  isActive: u.status === 'active'
}));

// With types: guaranteed to work or won't compile
interface ApiUser {
  first: string;
  last: string;
  status: 'active' | 'inactive';
}

interface User {
  fullName: string;
  isActive: boolean;
}

const users: User[] = response.data.map((u: ApiUser) => ({
  fullName: u.first + ' ' + u.last,
  isActive: u.status === 'active'
}));

5. Shared Libraries

If you're building code that others will use (npm packages, internal libraries), TypeScript provides automatic documentation and IDE support for consumers.

When Plain JavaScript is Better

1. Prototypes and Experiments

When you're exploring an idea, types slow you down. You're changing everything constantly. Type definitions become busywork that gets outdated immediately.

Build the prototype in JavaScript. Once the concept is proven and the structure is stable, consider adding types.

2. Scripts and One-Offs

That data migration script you'll run once? The build tool config? The quick automation task? Types add nothing but overhead.

These scripts don't need long-term maintenance or team collaboration. Keep them simple.

3. Small Projects (<2000 Lines)

For genuinely small projects, you can understand the whole codebase quickly. The safety benefits of TypeScript don't outweigh the configuration overhead.

Exception: if the small project will grow, start with TypeScript. Migrating later is painful.

4. Performance-Critical Hot Paths

TypeScript compiles to JavaScript, so runtime performance is usually identical. But if you're micro-optimizing, the generated JavaScript sometimes has overhead. Profile first, but be aware it can matter in tight loops.

5. Learning or Teaching JavaScript

If someone is learning JavaScript, TypeScript adds confusion. The core language is complex enough without also learning a type system.

Master JavaScript first. Add TypeScript once the fundamentals are solid.

My Decision Framework

When evaluating whether to use TypeScript, I ask these questions:

Question 1: How long will this code live?

• Days/weeks: Plain JS
• Months: Consider TypeScript
• Years: TypeScript

Question 2: How many people will touch it?

• Just me: Plain JS is fine for smaller projects
• 2-3 people: TypeScript helps
• 4+ people: TypeScript is essential

Question 3: How complex is the data?

• Simple primitives: Plain JS
• Nested objects, unions, transformations: TypeScript

Question 4: Is the structure stable?

• Changing daily: Plain JS until stable
• Mostly settled: TypeScript

The Middle Ground: JSDoc

There's a middle option that's underappreciated: JSDoc type annotations in plain JavaScript.

/**
 * @param {string} name
 * @param {number} age
 * @returns {{ greeting: string, isAdult: boolean }}
 */
function createUser(name, age) {
  return {
    greeting: `Hello, ${name}`,
    isAdult: age >= 18
  };
}

With proper JSDoc:

• VS Code gives you full IntelliSense
• You can enable TypeScript checking with a config flag
• No build step required
• Easy to add incrementally

For projects where full TypeScript feels like overkill but you want some type safety, JSDoc is a solid choice.

Migration Tips (If You Decide to Convert)

If you're converting an existing JavaScript project to TypeScript:

1. Start with strict: false - Get everything compiling first, then tighten strictness incrementally
2. Rename files gradually - Convert .js to .ts one file at a time, starting with leaf nodes (files that don't import others)
3. Use any liberally at first - Replace with proper types over time. A working codebase with some any is better than a broken codebase with perfect types
4. Type external boundaries first - API responses, library interfaces. These are where type bugs usually originate
5. Don't block features on migration - Convert incrementally alongside normal development

The Bottom Line

TypeScript is a tool, not a religion. It solves real problems, but not every problem.

Use TypeScript when:

• The project is large or will become large
• Multiple developers are involved
• The code will be maintained long-term
• Data structures are complex

Stick with JavaScript when:

• You're prototyping or experimenting
• The project is small and simple
• It's a one-off script
• Speed of iteration matters more than long-term maintenance

Don't let peer pressure push you either direction. Evaluate your specific context and choose the tool that actually fits.