JavaScript vs TypeScript: What’s the Difference?

The Short Answer

The relationship between the two languages is not “old versus new” or “one replaces the other.” It is a superset relationship, and that single fact explains almost everything else.

The practical consequence: every valid JavaScript file is already a valid TypeScript file. If you rename app.js to app.ts, it compiles and runs identically. TypeScript does not reject JavaScript — it accepts all of it, and gives you the option to add types on top.

JavaScript in One Paragraph

JavaScript is the programming language that runs in the browser. It is dynamically typed, which means a variable can hold a number now and a string later, and the language will not object. Types exist at runtime — the value 42 knows it is a number — but nothing checks that you are using it correctly before the program runs.

// JavaScript — no type annotations, no compile-time checking

function add(a, b) {
    return a + b;
}

add(2, 3);        // 5      — what you intended
add('2', 3);      // '23'   — no error, just wrong
add(2);           // NaN    — no error, just wrong

All three calls run without complaint. The second one returns the string "23" because JavaScript converts the number to a string when one operand is a string. The third returns NaN because 2 + undefined is not a number. Neither throws. Neither warns. The bug travels silently until it reaches something that breaks.

TypeScript in One Paragraph

TypeScript adds a static type system to JavaScript. You annotate what kinds of values your functions accept and return, and the compiler checks those annotations before the code runs. If you call a function with the wrong type, you get an error in your editor immediately — not a bug report next week.

// TypeScript — the same function, with types

function add(a: number, b: number): number {
    return a + b;
}

add(2, 3);        // 5      — fine
add('2', 3);      // ❌ Error: Argument of type 'string'
                  //    is not assignable to parameter
                  //    of type 'number'.
add(2);           // ❌ Error: Expected 2 arguments,
                  //    but got 1.

Both of the broken calls are caught in the editor, before anything runs. That is the entire value proposition, and it applies everywhere: function arguments, object shapes, array contents, return values, and null checks.

What the compiler produces

Once the types have been checked, the compiler strips them out. The JavaScript that actually runs is identical to what you would have written by hand.

The Same Function in Both Languages

Here is a small, complete example — a function that formats a user’s name — written first in JavaScript, then in TypeScript. The logic is identical. The difference is what each version tells the compiler, and what the compiler can then catch.

JavaScript version

function formatUser(user) {
    return {
        name: user.firstName + ' ' + user.lastName,
        email: user.email.toLowerCase(),
        isAdmin: user.role === 'admin'
    };
}

// Nothing here is checked.
// If user has no email, this throws at runtime.
// If user.firstName is a number, this silently produces garbage.
formatUser({ firstName: 'Ada', lastName: 'Lovelace', email: 'ADA@X.COM', role: 'admin' });

TypeScript version

interface User {
    firstName: string;
    lastName: string;
    email: string;
    role: 'admin' | 'editor' | 'viewer';
}

interface FormattedUser {
    name: string;
    email: string;
    isAdmin: boolean;
}

function formatUser(user: User): FormattedUser {
    return {
        name: user.firstName + ' ' + user.lastName,
        email: user.email.toLowerCase(),
        isAdmin: user.role === 'admin'
    };
}

The TypeScript version is nine lines longer, and in exchange it checks four things before the code ever runs:

• Every property exists. user.firstName is valid — user.firstname is an error.
• Every property has the right type. Passing a number as firstName is an error.
• The role is one of three values. 'admin', 'editor', or 'viewer' — nothing else compiles.
• The return value matches. If you forget to return isAdmin, the compiler objects.

What TypeScript Catches

The most convincing argument for TypeScript is the class of bugs it eliminates. Here is the same buggy code in both languages, side by side.

The categories of bugs TypeScript eliminates

The Type System in Practice

TypeScript’s type system goes well beyond “this is a string.” These are the features you will use most.

Primitive types

const name: string  = 'Ada';
const age: number   = 36;
const active: boolean = true;

// Arrays
const scores: number[] = [90, 85, 72];
const names: string[] = ['Ada', 'Grace'];    // or Array<string>

// Tuples — fixed length, fixed types
const point: [number, number] = [10, 20];

Interfaces and type aliases

Both describe the shape of an object. interface is preferred for object shapes because it can be extended; type is more flexible and can also describe unions and primitives.

interface Product {
    id: number;
    name: string;
    price: number;
    tags?: string[];      // optional — the ? makes it optional
}

// Extending an interface
interface DiscountedProduct extends Product {
    discountPercent: number;
}

// A type alias for a union
type Status = 'pending' | 'shipped' | 'delivered';

// A type alias for an object
type Point = { x: number; y: number };

Union types — the most useful feature

A union says a value can be one of several things. Combined with a narrowed check, it makes impossible states genuinely impossible.

type Status = 'pending' | 'shipped' | 'delivered';

function describe(status: Status): string {
    switch (status) {
        case 'pending':   return 'Waiting to ship';
        case 'shipped':   return 'On the way';
        case 'delivered': return 'Arrived';
    }
}

describe('shipped');    // fine
describe('canceled');   // ❌ Error: not one of the allowed values

// Add a new status to the union and TypeScript will flag
// every switch statement that does not handle it.

Generics — types that take types

A generic lets a function or type work with many different types while keeping the relationship between them.

// Without generics, you would need `any` and lose all checking
function first<T>(items: T[]): T | undefined {
    return items[0];
}

first([1, 2, 3]);           // type: number | undefined
first(['a', 'b']);          // type: string | undefined

// The type is inferred from what you pass in,
// and the return type follows it exactly.

Beyond Types: What Else TypeScript Adds

The type system is the headline feature, but it unlocks a set of tooling improvements that matter just as much on a real project.

How TypeScript Runs

Browsers and Node.js do not understand TypeScript. Every .ts file has to be converted to .js before anything can execute it.

Setting up a project

TypeScript installs as an npm package. The tsconfig.json file controls how it behaves.

// Install TypeScript in a project
// npm install --save-dev typescript

// Create a tsconfig.json with sensible defaults
// npx tsc --init

A minimal tsconfig.json

{
    "compilerOptions": {
        "target": "ES2022",
        "module": "ESNext",
        "strict": true,
        "outDir": "./dist",
        "rootDir": "./src",
        "sourceMap": true
    },
    "include": ["src/**/*"]
}

The strict flag is the one that matters most. It turns on several checks at once, including strictNullChecks — which is what makes null and undefined explicit rather than silently allowed.

Modern build tools

The tsc compiler is the official tool, but most projects use a bundler that handles TypeScript alongside everything else.

JavaScript Still Runs Everything

It is worth being very clear about this, because it confuses a lot of beginners: the JavaScript you write in TypeScript is still JavaScript. The types are not a runtime feature.

Here is a live example. This is plain JavaScript running in a browser, doing exactly what it would do if it had been written in TypeScript and compiled.

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>What TypeScript Compiles To</title>
    <style>
        body {
            font-family: system-ui, sans-serif;
            padding: 28px;
            background: #f8fafc;
            margin: 0;
            color: #0f172a;
        }
        h2 { font-size: 14px; text-transform: uppercase; letter-spacing: 0.08em; color: #64748b; margin: 0 0 12px; }
        .row {
            background: #fff;
            border: 1px solid #e2e8f0;
            border-radius: 10px;
            padding: 12px 16px;
            margin-bottom: 8px;
            font-family: ui-monospace, monospace;
            font-size: 13px;
            display: flex;
            justify-content: space-between;
            gap: 12px;
        }
        .label { color: #64748b; }
        .value { color: #0891b2; font-weight: 700; }
    </style>
</head>
<body>

    <h2>The compiled output</h2>
    <div id="output"></div>

    <script>
        // This is the JavaScript that a TypeScript compiler
        // produces from a typed function. Notice:
        // — no type annotations remain
        // — no interface exists at runtime
        // — the logic is exactly what you wrote

        function add(a, b) {
            return a + b;
        }

        function formatUser(user) {
            return {
                name: user.firstName + ' ' + user.lastName,
                email: user.email.toLowerCase(),
                isAdmin: user.role === 'admin'
            };
        }

        const user = {
            firstName: 'Ada',
            lastName: 'Lovelace',
            email: 'ADA@EXAMPLE.COM',
            role: 'admin'
        };

        const formatted = formatUser(user);

        const rows = [
            { label: 'add(2, 3)',        value: add(2, 3) },
            { label: 'add("2", 3)',      value: add('2', 3) + '  ← string concat!' },
            { label: 'formatted.name',   value: formatted.name },
            { label: 'formatted.email',  value: formatted.email },
            { label: 'formatted.isAdmin', value: formatted.isAdmin },
            { label: 'typeof add',       value: typeof add }
        ];

        const out = document.getElementById('output');
        rows.forEach(function (row) {
            const div = document.createElement('div');
            div.className = 'row';
            div.innerHTML =
                '<span class="label">' + row.label + '</span>' +
                '<span class="value">' + row.value + '</span>';
            out.appendChild(div);
        });
    </script>

</body>
</html>

Note the second row: add('2', 3) returns "23". That is the bug TypeScript would have caught. But at runtime — after compilation — the JavaScript engine has no idea the types were ever annotated. It sees the same function it always would have.

Full Comparison

Here is every meaningful difference in one table.

When to Use Which

TypeScript is not automatically better. It has a real setup cost, and that cost is only worth paying when the project justifies it.

A practical rule of thumb

• Under 500 lines, one developer, one use: plain JavaScript.
• Over a few thousand lines, or a team: TypeScript.
• A library or package others will import: TypeScript, and ship the type definitions.
• A framework that ships with TS support: use TypeScript — you are already paying the setup cost.
• A quick script to move some files around: plain JavaScript, obviously.

Migrating from JavaScript to TypeScript

TypeScript was designed for gradual adoption. You do not rewrite the project — you convert it one file at a time while it keeps working.

The incremental path

What the migration looks like

Configuring for gradual adoption

{
    "compilerOptions": {
        "target": "ES2022",
        "module": "ESNext",

        // Allow .js files in the project
        "allowJs": true,

        // Report errors in .js files too (optional, stricter)
        "checkJs": false,

        // Do not fail the build on errors during migration
        "noEmitOnError": false,

        // Start loose, tighten later
        "strict": false,

        "outDir": "./dist",
        "rootDir": "./src"
    },
    "include": ["src/**/*"]
}

Common Misconceptions

These come up constantly, and each one leads people to the wrong decision about TypeScript.

• “TypeScript is a different language.” It is a superset. Every JavaScript program is a TypeScript program. You are not learning a new language — you are learning a type system on top of the one you already know.
• “TypeScript replaces JavaScript.” It compiles to JavaScript. The browser runs the JavaScript. Nothing about the runtime changes.
• “TypeScript is slower at runtime.” All the types are erased at compile time. The JavaScript that ships is byte-for-byte equivalent to what you would have written by hand.
• “I need to rewrite my whole project.” You can rename one file at a time. TypeScript was explicitly designed for incremental adoption, and mixed projects are supported natively.
• “Types catch all bugs.” They catch type errors. A function that adds when it should subtract compiles fine. Logic bugs are still logic bugs.
• “Types slow down development.” Early on, writing types is extra work. After a few weeks, most developers report the opposite — autocomplete and refactoring save more time than the annotations cost.
• “any is a fine escape hatch.” Occasional use is reasonable. Widespread any removes all the benefit while keeping all the syntax — you get JavaScript with extra steps.
• “TypeScript is only for big companies.” A solo developer on a project that will exist for a year benefits just as much. The threshold is project lifetime and change frequency, not team size.

Best Practices

If you are using TypeScript, these habits get the most out of it. If you are not, they are good reasons to consider it.

Key Takeaways

• TypeScript is JavaScript plus a static type system — a strict superset, not a replacement.
• Types are checked while you write, then erased before the code runs.
• Browsers and Node.js run JavaScript. TypeScript must be compiled first.
• Type annotations leave no trace in the output, so there is zero runtime cost.
• TypeScript catches typos, wrong argument types, missing arguments, null access, and wrong return types.
• It does not catch logic errors — a function that adds instead of subtracting compiles fine.
• The biggest practical benefit is editor autocomplete and safe refactoring.
• Use plain JavaScript for scripts, prototypes, and learning.
• Use TypeScript for applications, teams, libraries, and long-lived codebases.
• Migration is incremental — rename one file at a time, keep the project working.
• Turn on strict mode and avoid any.
• Transpilers like esbuild skip type checking — run tsc --noEmit in CI.

What to Learn Next

If you are new to JavaScript entirely, start there. Read What Is JavaScript? for the fundamentals — variables, functions, arrays, objects, the DOM, and events.

Once the basics are solid, the natural next steps are JavaScript Array Methods, JavaScript Functions Explained, and Working with the DOM. From there, move on to Async and Await and Fetching Data with the Fetch API.

If you are ready for TypeScript, look for guides on the type system itself — interfaces, unions, generics, and tsconfig.json. And if you are still connecting the pieces, read HTML vs CSS and How Web Browsers Work for the surrounding context.

Practice Challenge

The best way to understand the difference is to write the same code twice and see what each language catches. This exercise takes about twenty minutes.

1. Create app.js and app.ts in the same folder.
2. In both files, write a function calculateTotal(price, quantity) that returns price * quantity, with no type annotations in either file.
3. Add a line that calls calculateTotal('10', 3) and logs the result. Run the JavaScript version and note the output — it will be the string "101010".
4. Now install TypeScript with npm install --save-dev typescript and run npx tsc --init to create a tsconfig.json. Set strict to true.
5. Compile the TypeScript file with npx tsc app.ts. Read the error — it will point at the string argument.
6. Fix the call to pass 10 instead of '10'. Compile again — it succeeds.
7. Open the compiled app.js and compare it to your original. Confirm that the output contains no type annotations at all.
8. Now add types to the function: function calculateTotal(price: number, quantity: number): number.
9. Try calling it with a missing argument. Note the error message — it names the exact problem and the line.
10. Create an interface Product { name: string; price: number; } and write a function that takes a Product. Try accessing a property that does not exist — note the error.
11. Add a union type: type Status = 'in-stock' | 'out-of-stock', and write a function that accepts it. Try passing a string that is not one of the two values.
12. Finally, compare the compiled output of your fully typed app.ts against the original app.js. Confirm they are functionally identical.

If you complete those steps, you have seen the same bug happen silently in JavaScript and get caught immediately in TypeScript, watched the compiler strip every annotation from the output, and confirmed that the runtime behavior is unchanged. That is the whole trade: TypeScript does not change what your program does — it changes when you find out that it does the wrong thing.