Adding TypeScript to an existing React project can feel like a herculean task.

Let's break it down into a few simple steps.

## Step 1: Install TypeScript

You'll first need to install TypeScript as a dev dependency:

```bash
npm install --save-dev typescript
```

## Step 2: Add a `tsconfig.json` file

Next, you'll need to add a `tsconfig.json` file to the root of your project. This file tells TypeScript how to compile your code.

I don't recommend using `tsc --init` for this. It will generate a lot of unnecessary comments and hard-to-read defaults.

Instead, I recommend going to the [tsconfig/bases](https://github.com/tsconfig/bases/tree/main/bases) repo to find a `tsconfig.json` file that matches your project.

They have different `tsconfig.json` files for different project types:

- [Create React App](https://github.com/tsconfig/bases/blob/main/bases/create-react-app.json)
- [Next.js](https://github.com/tsconfig/bases/blob/main/bases/next.json)
- [Vite with React](https://github.com/tsconfig/bases/blob/main/bases/vite-react.json)
- [Remix](https://github.com/tsconfig/bases/blob/main/bases/remix.json)
- [React Native](https://github.com/tsconfig/bases/blob/main/bases/react-native.json)

## Step 3: Change a File To `.ts` (or `.tsx`)

Next, you'll need to change a file to `.ts` (or `.tsx` if it contains a React component).

With the vast majority of modern projects, your framework of choice will be able to _just work_ with the new `.ts` file. This is because most bundlers (which frameworks use to compile your code) can handle both JavaScript and TypeScript.

If it doesn't head to that framework's TypeScript documentation to see what extra steps you need to take.

## Step 4: Begin The Migration

Now that you have TypeScript installed and a `tsconfig.json` file, you can begin the migration.

If your project is anything larger than a few files, I recommend migrating one file at a time. This will help you avoid merge conflicts and make it easier to find bugs.

It'll also mean that any existing PRs don't need to be rewritten to include the TypeScript changes.

Your project might be in a stage where it has lots of JavaScript files AND lots of TypeScript files. This is fine as an intermediate step, and you should be able to keep shipping features while this change occurs.

I recommend Sentry's [Migrating to TypeScript](https://blog.sentry.io/slow-and-steady-converting-sentrys-entire-frontend-to-typescript/) blog post for more information on how to do this.


Learn how to add TypeScript to your existing React project in a few simple steps.

Add TypeScript To An Existing React Project

Today is the biggest ship day of my life. After 11 months of work, I'm launching:

- Total TypeScript Essentials: a 16-chapter [TypeScript book](https://www.totaltypescript.com/books/total-typescript-essentials), for FREE.
- [Pro Essentials](https://www.totaltypescript.com/workshops/typescript-pro-essentials): a new, 200-exercise course for $200.
- A giveaway worth ~$80,000 to existing customers.
- A huge price cut on Total TypeScript.
- A 20% sale until Friday.

Here's the full story:

## The Book - Total TypeScript: Essentials

My book, [Total TypeScript: Essentials](https://www.totaltypescript.com/books/total-typescript-essentials), is finally ready.

It's been 11 months of work. 16 chapters. Hundreds of pages. And it's free.

It covers everything you need to get a job with TypeScript, from setting up your IDE to understanding generics.

And it's 100% freely available on Total TypeScript. Forever.

We'll also be releasing this as a printed book! You can pre-order a copy on [No Starch's site](https://nostarch.com/total-typescript).

## The Course - Pro Essentials

We're also releasing a new course, [Pro Essentials](https://www.totaltypescript.com/workshops/typescript-pro-essentials).

It's the ultimate TypeScript masterclass - the no-brainer training programme to help your team build TypeScript apps.

It contains over 200 exercises and requires no TypeScript experience.

And, until Friday, it's $200.

Pro Essentials is different from everything else I've shipped.

Before, I focused on advanced content to turn you into a TS wizard. The content in the [Core Volume](https://www.totaltypescript.com/workshops) is perfect for this.

But with Essentials (the book) and Pro Essentials (the course), I want Total TypeScript to be the default choice for teams.

Got a team transitioning to TS? Get them Pro Essentials, at $200 a pop (cheaper in bulk) and you'll have some happy engineers working at max capacity.

## Price Cut and Giveaway

We've slashed the price of Total TypeScript. You can now pick up the entire of TT, including Pro Essentials, for $500.

And until Friday, it's 20% off: $400.

This is a HUGE drop from where it was before.

What about the folks that already paid the higher price for the existing workshops?

Existing TT customers will get Pro Essentials for free. Over all our customers, that's around $80,000 of giveaway.

I'm so excited to finally share this with you. I hope you enjoy it as much as I enjoyed creating it.


It's a massive ship day. We're launching a free TypeScript book, new course, giveaway, price cut, and sale.

Announcing: A Free Book, A New Course, A Huge Price Cut...

Sometimes, the way you order your object properties matters.

## The Setup

Let's imagine we create a function that takes in an object as its argument. In this object, there are two properties: `produce` and `consume`.

```ts twoslash
const process = <T>(obj: {
  produce: (input: string) => T;
  consume: (t: T) => void;
}) => {
  const value = obj.produce("abc");
  obj.consume(value);
};

// ---cut---

process({
  produce: (input) => Number(input),
  consume: (output) => console.log(output),
  //                               ^?
});
```

`produce` takes in an input of `string` and returns some type. `consume` then takes in that value and does something with it. Because of a clever type definition, TypeScript can infer the type of the value returned by `produce` and pass it to `consume`:

```ts twoslash
const process = <T>(obj: {
  produce: (input: string) => T;
  consume: (t: T) => void;
}) => {
  const value = obj.produce("abc");
  obj.consume(value);
};
```

We can use this setup with any type of value, and it'll just work:

```ts twoslash
const process = <T>(obj: {
  produce: (input: string) => T;
  consume: (t: T) => void;
}) => {
  const value = obj.produce("abc");
  obj.consume(value);
};

// ---cut---
process({
  produce: (input) => input + "hello",
  consume: (output) => console.log(output),
  //                               ^?
});

process({
  produce: (input) => ({ value: input }),
  consume: (output) => console.log(output),
  //                               ^?
});
```

## The Problem

This all looks great, until one of our users complains to us. They're trying to use our function, but it's not working:

```ts twoslash
const process = <T>(obj: {
  produce: (input: string) => T;
  consume: (t: T) => void;
}) => {
  const value = obj.produce("abc");
  obj.consume(value);
};

// ---cut---

process({
  consume: (output) => console.log(output),
  //                               ^?
  produce: (input) => Number(input),
});
```

The `output` is being seen by TypeScript as `unknown`. This feels very odd, as the `produce` function is clearly returning a `number`. What's going on?

The difference here is that the user specified `consume` _before_ `produce`. Since TypeScript 4.7, in [this PR](https://github.com/microsoft/TypeScript/pull/48538), TypeScript now uses the order of properties to inform its inference. This was added to fix various long-standing bugs (linked in the PR) with context-sensitive functions.

This means that, in some very narrow cases, the order you specify your properties matters. So if you're running up against strange errors to do with property ordering, that's why!

## Could You Use `NoInfer`?

You might be wondering if you could use [`NoInfer`](https://www.totaltypescript.com/noinfer) to fix this. That seems sensible, given that `NoInfer` is used to force TypeScript to avoid inference on certain targets.

However, it doesn't:

```ts twoslash
const process = <T>(obj: {
  produce: (input: string) => T;
  consume: NoInfer<(t: T) => void>;
}) => {
  const value = obj.produce("abc");
  obj.consume(value);
};

process({
  consume: (output) => console.log(output),
  //                               ^?
  produce: (input) => Number(input),
});
```

The result is still `unknown`. How frustrating!


Learn why the order you specify object properties in TypeScript matters and how it can affect type inference in your functions.

Sometimes, Object Property Order Matters

I've just learned about `corepack`, a tool that bundles with Node.js and solves a bunch of problems with handling package managers. But I'll be using it in my development setup from now on.

## Quick Start

### Step 1. Global Install

`corepack` is bundled with Node.js, and has been since Node.js 14.19. So, if you have Node.js, you have `corepack`.

You can enable `corepack` on your machine by running the following command:

```bash
corepack enable && corepack enable npm
```

This enables `corepack` globally - you don't need to enable it per project.

### Step 2. Configure Your Project

`corepack` makes sure you're using the correct package manager for your project. To configure the package manager for your project, add the `packageManager` field to your `package.json`:

```json
{
  // npm
  "packageManager": "npm@10.8.1",
  // pnpm
  "packageManager": "pnpm@9.1.4",
  // yarn
  "packageManager": "yarn@3.1.1"
}
```

You must specify an _exact_ version of the package manager you want to use - not a range. All of the below are not valid:

```json
{
  // not valid: uses a range
  "packageManager": "npm@^10.8.1",

  // not valid: specifies 'latest'
  "packageManager": "pnpm@latest",

  // not valid: must specify an exact version
  "packageManager": "yarn"
}
```

### Step 3. Try It Out

Now, if you try to `npm install` in a project that has `packageManager` set to `pnpm`, `corepack` will show an error:

```txt
Usage Error: This project is configured to use pnpm

$ npm ...
```

And if you try to `pnpm install` there, `corepack` will automatically download and use the correct `pnpm` version:

```txt
Corepack is about to download https://registry.npmjs.org/pnpm/-/pnpm-9.1.4.tgz.

Do you want to continue? [Y/n]
```

This ensures you're always using the correct package manager for your project.

## Why Do We Need `corepack enable npm`?

`corepack` intercepts calls to `pnpm` and `yarn` to make sure you're using them correctly. This is set up by running `corepack enable`.

Without running `corepack enable npm`, you won't get the same validation when using `npm`. So, we run `corepack enable npm` to make sure that `npm` gets treated the same way as `pnpm` and `yarn`.

## Why Use Corepack?

I ran out of time to continue writing this article. Want me to keep going? What questions do you have? Let me know:

<FeedbackFormButton />


Learn how to use `corepack` to configure package managers in Node.js projects, ensuring you always use the correct one.

How To Use Corepack

A common problem in TypeScript is that `process.env` doesn't give you autocomplete for the environment variables that actually exist in your system:

```ts twoslash
declare const process: {
  env: Record<string, string | undefined>;
};

// ---cut---

console.log(process.env.MY_ENV_VARIABLE); // No autocomplete
```

They also end up typed as `string | undefined`, which can be annoying if you're passing them into functions that expect a string:

```ts twoslash
// @errors: 2345
declare const process: {
  env: Record<string, string | undefined>;
};

// ---cut---

const myFunc = (envVar: string) => {
  console.log(envVar.toUpperCase());
};

myFunc(process.env.MY_ENV_VARIABLE);
```

Here are a few ways to strongly type `process.env`:

## Solution 1: Augment The Global Type

You can augment the global type `NodeJS.ProcessEnv` to include your environment variables:

```ts
// globals.d.ts
namespace NodeJS {
  interface ProcessEnv {
    MY_ENV_VARIABLE: string;
  }
}
```

This relies on declaration merging on the global interface `NodeJS.ProcessEnv`, adding an extra property `MY_ENV_VARIABLE`.

Now, in every file in your project, you'll get autocomplete for `MY_ENV_VARIABLE`, and it'll be typed as a string.

```ts twoslash
// @errors: 2345
declare const process: {
  env: {
    MY_ENV_VARIABLE: string;
  };
};

const myFunc = (envVar: string) => {
  console.log(envVar.toUpperCase());
};

// ---cut---

myFunc(process.env.MY_ENV_VARIABLE);
//                 ^?
```

However, this doesn't provide any guarantees that the environment variable actually exists in your system.

This means that it's useful when you have relatively few environment variables, or can't get buy-in to add an extra library for checking them.

## Solution 2: Validate It At Runtime With `t3-env`

If you want to validate that all your environment variables are present at runtime, you can use a library like [`t3-env`](https://github.com/t3-oss/t3-env).

This leverages zod to validate your environment variables at runtime. Here's an example:

```ts
import { createEnv } from "@t3-oss/env-core";
import { z } from "zod";

export const env = createEnv({
  server: {
    DATABASE_URL: z.string().url(),
    OPEN_AI_API_KEY: z.string().min(1),
  },
  clientPrefix: "PUBLIC_",
  client: {
    PUBLIC_CLERK_PUBLISHABLE_KEY: z.string().min(1),
  },
  runtimeEnv: process.env,
});
```

This will fail at runtime if any of the environment variables are missing or don't match the schema. It also means you can leverage Zod's powerful validation capabilities, such as `.url()` or `.min(1)` for strings.

It also provides a single source of truth for your environment variables - `env`. This means you can use `env` throughout your codebase, and you'll get autocomplete and type-checking for your environment variables.

Here's a [great guide](https://env.t3.gg/docs/core) you can use to get started.

## Which Solution Should You Use?

If your project is small and you don't want to add extra dependencies, augmenting the global type is a good solution.

But if you're remotely concerned about missing environment variables at runtime, `t3-env` is a great choice.


Learn how to strongly type process.env in TypeScript by either augmenting global type or validating it at runtime with t3-env.

How To Strongly Type process.env

`any` is an extremely powerful type in TypeScript. It lets you treat a value as if you were in JavaScript, not TypeScript. This means that it disables all of TypeScript's features - type checking, autocomplete, and safety.

```ts twoslash
const myFunction = (input: any) => {
  input.someMethod();
};

myFunction("abc"); // This will fail at runtime!
```

Using `any` is rightly considered harmful by most of the community. There are [ESLint rules](https://typescript-eslint.io/rules/no-explicit-any/) to prevent its use. This can turn developers off using `any` entirely.

However, there are a few advanced cases where `any` is always the right choice. Here are some of them:

## Type Argument Constraints

Let's imagine we wanted to implement the `ReturnType` utility in TypeScript. This utility takes a function type and returns the type of its return value.

We need to create a [generic type](https://www.totaltypescript.com/no-such-thing-as-a-generic#generic-types) which takes a function type as a type argument. If we restricted ourselves to not use `any`, we might use `unknown`:

```ts twoslash
// @moduleDetection: force
type ReturnType<T extends (...args: unknown[]) => unknown> =
  // Not important for our explanation:
  T extends (...args: unknown[]) => infer R ? R : never;
```

It's not important to understand _all_ of this code, only the constraint - `T extends (...args: unknown[]) => unknown`. What we're saying here is that only functions which accept an arguments array of `unknown[]` and return `unknown` are allowed.

It seems to work fine for functions which have no arguments:

```ts twoslash
// @moduleDetection: force
type ReturnType<T extends (...args: unknown[]) => unknown> =
  T extends (...args: unknown[]) => infer R ? R : never;

// ---cut---

const myFunction = () => {
  console.log("Hey!");
};

type Result = ReturnType<typeof myFunction>;
//   ^?
```

But it stops working as soon as we add an argument:

```ts twoslash
// @moduleDetection: force
// @errors: 2344
type ReturnType<T extends (...args: unknown[]) => unknown> =
  T extends (...args: unknown[]) => infer R ? R : never;

// ---cut---

const myFunction = (input: string) => {
  console.log("Hey!");
};

type Result = ReturnType<typeof myFunction>;
```

In fact, it only works if we change the parameter of our function to `input: unknown`:

```ts twoslash
// @moduleDetection: force
type ReturnType<T extends (...args: unknown[]) => unknown> =
  T extends (...args: unknown[]) => infer R ? R : never;

// ---cut---

const myFunction = (input: unknown) => {
  console.log("Hey!");
};

type Result = ReturnType<typeof myFunction>;
//   ^?
```

So accidentally, we've created a `ReturnType` function that only works on functions which accept `unknown` as an argument. This is not what we wanted. We wanted it to work on any function.

The solution is to use `any[]` as the type argument constraint:

```ts twoslash
// @moduleDetection: force
type ReturnType<T extends (...args: any[]) => any> =
  T extends (...args: any[]) => infer R ? R : never;

const myFunction = (input: string) => {
  console.log("Hey!");
};

type Result = ReturnType<typeof myFunction>;
//   ^?
```

Now it works as expected. We're declaring that we don't care what types the function accepts - it could be anything.

The reason this is safe is because we're deliberately declaring a wide type. We're saying "I don't care what the function accepts, as long as it's a function". This is a safe use of `any`.

## Returning Conditional Types From Generic Functions

In some places, TypeScript's narrowing abilites are not as good as we'd like them to be. Let's say we want to create a function which returns different types based on a condition:

```ts twoslash
const youSayGoodbyeISayHello = (
  input: "hello" | "goodbye"
) => {
  if (input === "goodbye") {
    return "hello";
  } else {
    return "goodbye";
  }
};

const result = youSayGoodbyeISayHello("hello");
//    ^?
```

This function isn't really doing what we want it to. We want it to return the type `"goodbye"` when we pass in `"hello"`. But currently, `result` is typed as `"hello" | "goodbye"`.

We can fix this by using a conditional type:

```ts twoslash
// @noErrors
const youSayGoodbyeISayHello = <
  TInput extends "hello" | "goodbye"
>(
  input: TInput
): TInput extends "hello" ? "goodbye" : "hello" => {
  if (input === "goodbye") {
    return "hello";
  } else {
    return "goodbye";
  }
};

const goodbye = youSayGoodbyeISayHello("hello");
//    ^?
const hello = youSayGoodbyeISayHello("goodbye");
//    ^?
```

We've added a conditional type to the return type of the function which mirrors our runtime logic. If `TInput`, inferred from the runtime argument `input`, is `"hello"`, we return `"goodbye"`. Otherwise, we return `"hello"`.

But there's a problem. I've deliberately disabled the errors in the snippet above. Let's see what happens when we enable them:

```ts twoslash
// @errors: 2322
const youSayGoodbyeISayHello = <
  TInput extends "hello" | "goodbye"
>(
  input: TInput
): TInput extends "hello" ? "goodbye" : "hello" => {
  if (input === "goodbye") {
    return "hello";
  } else {
    return "goodbye";
  }
};
```

Ouch. TypeScript doesn't seem to be matching up the conditional type with the runtime logic. `"hello"` or `"goodbye"` can't be returned from the function.

We can fix this by using `as`, and forcing it to be the correct conditional type:

```ts twoslash
// @errors: 2322
const youSayGoodbyeISayHello = <
  TInput extends "hello" | "goodbye"
>(
  input: TInput
): TInput extends "hello" ? "goodbye" : "hello" => {
  if (input === "goodbye") {
    return "hello" as TInput extends "hello"
      ? "goodbye"
      : "hello";
  } else {
    return "goodbye" as TInput extends "hello"
      ? "goodbye"
      : "hello";
  }
};
```

We can make this nicer by extracting that logic to a common generic type:

```ts twoslash
// @errors: 2322

type YouSayGoodbyeISayHello<
  TInput extends "hello" | "goodbye"
> = TInput extends "hello" ? "goodbye" : "hello";

const youSayGoodbyeISayHello = <
  TInput extends "hello" | "goodbye"
>(
  input: TInput
): YouSayGoodbyeISayHello<TInput> => {
  if (input === "goodbye") {
    return "hello" as YouSayGoodbyeISayHello<TInput>;
  } else {
    return "goodbye" as YouSayGoodbyeISayHello<TInput>;
  }
};
```

But in these situations, it often makes more sense to use `as any`:

```ts twoslash
// @errors: 2322
const youSayGoodbyeISayHello = <
  TInput extends "hello" | "goodbye"
>(
  input: TInput
): TInput extends "hello" ? "goodbye" : "hello" => {
  if (input === "goodbye") {
    return "hello" as any;
  } else {
    return "goodbye" as any;
  }
};
```

Yes, this does make our function less type-safe. We could accidentally return `"bonsoir"` from the function instead.

But in these situations, it's often better to use `as any` and add a unit test for this function's behavior. Because of TypeScript's limitations in checking this stuff, this is often as close as you'll get to type safety.

There are several other use cases like this, where inside generic functions you need to use `any` to get around TypeScript's limitations. To me, this is fine.

## Conclusion

A question remains: should you ban `any` from your codebase? I think, on balance, the answer should be yes. You should turn on the ESLint rule which prevents its use, and you should avoid it wherever possible.

However, there _are_ cases where `any` is needed. They're worth using `eslint-disable` to get around them. So, bookmark this article, and attach it to your PR's when you feel the need to use it.

Have you spotted any other legitimate use cases for `any`? Let me know!

<FeedbackFormButton />


Discover when it's appropriate to use TypeScript's `any` type despite its risks. Learn about legitimate cases where `any` is necessary.

`any` Considered Harmful, Except For These Cases

I tend to get involved in a lot of discussions about TypeScript online. And one of the most common misconceptions I see from folks just learning about TypeScript is that TypeScript's types exist at runtime.

This idea feels obvious when you come to TypeScript from other strongly-typed languages. In those languages, types are a fundamental part of the language. They're used to influence the runtime behavior of the program.

But TypeScript is different - TypeScript's types don't exist at runtime. They're only used to help you catch errors at compile time. This is because TypeScript is designed to compile down to JavaScript, which doesn't have a type system.

Let's look at a few examples:

## Types

Types and interfaces let you describe the shape of a type. You will have thousands of lines of type declarations in your program. But they don't exist at runtime:

<TranspilePreview>

```ts
type Person = {
  name: string;
  age: number;
};

const person: Person = {
  name: "Alice",
  age: 30,
};

interface Animal {
  name: string;
  age: number;
}

const animal: Animal = {
  name: "Fluffy",
  age: 5,
};
```

</TranspilePreview>

Notice how the types `Person` and `Animal` are gone in the transpiled JavaScript, and all you're left with is the object literals.

## Type Assertions

You can use type assertions to tell TypeScript that you know more about a value than it does. But these assertions don't exist at runtime:

<TranspilePreview>

```ts
const str = "Hello, world!";

const num: number = str as unknown as number;
```

</TranspilePreview>

Just because `num` has been asserted to be a number doesn't mean it is one at runtime. TypeScript will trust you that `str` is a number, but if it's not, you'll get a runtime error.

This is a reason why type assertions are discouraged in TypeScript. They can lead to runtime errors if you're not careful.

## Function Parameters

You can use types to describe the shape of a function's parameters. But these types don't exist at runtime. They don't guarantee that your function will be called with the right arguments:

<TranspilePreview>

```ts
const add = (a: number, b: number) => a + b;

add(1, 2);

add("1" as any, "2" as any);
```

</TranspilePreview>

Notice that there is no extra code in the transpiled JavaScript to check that `add` is being called with the right arguments.

## Enums, Namespaces and Parameter Properties

There are some exceptions to this rule. Enums, namespaces, and parameter properties do have a runtime representation:

<TranspilePreview>

```ts
// Enums
enum Direction {
  Up,
  Down,
  Left,
  Right,
}

// Namespaces
namespace Geometry {
  export const PI = 3.14159;
}

// Parameter Properties
class Person {
  constructor(public name: string) {}
}
```

</TranspilePreview>

Most features in TypeScript disappear at runtime, but these three are the exception. They have a runtime representation that can be used in your program.

These features are all pretty old. They were added in an era when JavaScript was seen as relatively stagnant - and TypeScript was attractive because it added much-needed features like enums, classes and namespaces.

But now, JavaScript is in a much healthier place. It has classes built in. It has modules, which are an improved version of namespaces. Someday, according to [this proposal](https://github.com/rbuckton/proposal-enum), it might have enums.

So now, TypeScript takes a different approach - it sees its job as adding types to JavaScript, not adding new features to the language. If enums, namespaces or parameter properties were proposed now, they wouldn't be added to TypeScript.

This means that thinking of TypeScript as just adding types to JavaScript is a useful rule of thumb - with the exception of enums, namespaces and parameter properties.


Learn why TypeScript's types don't exist at runtime. Discover how TypeScript compiles down to JavaScript and how it differs from other strongly-typed languages.

Step 1: Install TypeScript

Step 2: Add a tsconfig.json file

Step 3: Change a File To .ts (or .tsx)

Step 4: Begin The Migration

Step 2: Add a `tsconfig.json` file

Step 3: Change a File To `.ts` (or `.tsx`)