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

`tsconfig.json` scares everyone. It's a huge file with a TON of potential options.

But really, there are only a few configuration options you need to care about. Let's figure them out, and cheatsheet them.

## Quickstart

Want just the code? Here you go:

```json
{
  "compilerOptions": {
    /* Base Options: */
    "esModuleInterop": true,
    "skipLibCheck": true,
    "target": "es2022",
    "verbatimModuleSyntax": true,
    "allowJs": true,
    "resolveJsonModule": true,
    "moduleDetection": "force",

    /* Strictness */
    "strict": true,
    "noUncheckedIndexedAccess": true,

    /* If transpiling with TypeScript: */
    "moduleResolution": "NodeNext",
    "module": "NodeNext",
    "outDir": "dist",
    "sourceMap": true,

    /* If NOT transpiling with TypeScript: */
    "moduleResolution": "Bundler",
    "module": "ESNext",
    "noEmit": true,

    /* If your code runs in the DOM: */
    "lib": ["es2022", "dom", "dom.iterable"],

    /* If your code doesn't run in the DOM: */
    "lib": ["es2022"],

    /* If you're building for a library: */
    "declaration": true,

    /* If you're building for a library in a monorepo: */
    "composite": true,
    "declarationMap": true
  }
}
```

## Full Explanation

### Base Options

Here are the base options I recommend for all projects.

```json
{
  "compilerOptions": {
    "esModuleInterop": true,
    "skipLibCheck": true,
    "target": "es2022",
    "verbatimModuleSyntax": true,
    "allowJs": true,
    "resolveJsonModule": true,
    "moduleDetection": "force"
  }
}
```

- [`esModuleInterop`](https://www.typescriptlang.org/tsconfig#esModuleInterop): Helps mend a few of the fences between CommonJS and ES Modules.
- [`skipLibCheck`](https://www.typescriptlang.org/tsconfig#skipLibCheck): Skips checking the types of `.d.ts` files. This is important for performance, because otherwise all `node_modules` will be checked.
- [`target`](https://www.typescriptlang.org/tsconfig#target): The version of JavaScript you're targeting. I recommend `es2022` over `esnext` for stability.
- [`verbatimModuleSyntax`](https://www.typescriptlang.org/tsconfig#verbatimModuleSyntax): Gives you strict errors for `import` and `export` syntax in `.cts` and `.mts` files.
- [`allowJs`](https://www.typescriptlang.org/tsconfig#allowJs) and [`resolveJsonModule`](https://www.typescriptlang.org/tsconfig#resolveJsonModule): Allows you to import `.js` and `.json` files. Always useful.
- [`moduleDetection`](https://www.typescriptlang.org/tsconfig#moduleDetection): This option forces TypeScript to consider all files as modules. This helps to avoid '[cannot redeclare block-scoped variable](https://www.totaltypescript.com/cannot-redeclare-block-scoped-variable)' errors.

### Strictness

Here are the strictness options I recommend for all projects.

```json
{
  "compilerOptions": {
    "strict": true,
    "noUncheckedIndexedAccess": true
  }
}
```

- [`strict`](https://www.typescriptlang.org/tsconfig#strict): Enables all strict type checking options. Indispensable.
- [`noUncheckedIndexedAccess`](https://www.typescriptlang.org/tsconfig#noUncheckedIndexedAccess): Prevents you from accessing an array or object without first checking if it's defined. This is a great way to prevent runtime errors, and should _really_ be included in `strict`.

Many folks recommended the strictness options in [`tsconfig/bases`](https://github.com/tsconfig/bases/blob/031273b815ff7f672c7c9057fb7d19ef363054b1/bases/strictest.json), a wonderful repo which catalogs TSConfig options. These options include lots of rules which I consider too 'noisy', like [`noImplicitReturns`](https://www.typescriptlang.org/tsconfig#noImplicitReturns), [`noUnusedLocals`](https://www.typescriptlang.org/tsconfig#noUnusedLocals), [`noUnusedParameters`](https://www.typescriptlang.org/tsconfig#noUnusedParameters), and [`noFallthroughCasesInSwitch`](https://www.typescriptlang.org/tsconfig#noFallthroughCasesInSwitch). I recommend you add these rules to your `tsconfig.json` only if you want them.

### Transpiling with TypeScript

If you're transpiling your code (creating JavaScript files) with `tsc`, you'll want these options.

```json
{
  "compilerOptions": {
    "moduleResolution": "NodeNext",
    "module": "NodeNext",
    "outDir": "dist"
  }
}
```

- [`moduleResolution`](https://www.typescriptlang.org/tsconfig#moduleResolution): Tells TypeScript how to resolve modules. `NodeNext` is the best option for if the code you're writing is meant to be run in Node.
- [`module`](https://www.typescriptlang.org/tsconfig#module): Tells TypeScript what module syntax to use. `NodeNext` is the best option for Node.
- [`outDir`](https://www.typescriptlang.org/tsconfig#outDir): Tells TypeScript where to put the compiled JavaScript files. `dist` is my preferred convention, but it's up to you.

### Not Transpiling with TypeScript

If you're _not_ transpiling your code with `tsc`, i.e. using TypeScript as more of a linter, you'll want these options.

```json
{
  "compilerOptions": {
    "moduleResolution": "Bundler",
    "module": "ESNext",
    "noEmit": true
  }
}
```

- [`moduleResolution`](https://www.typescriptlang.org/tsconfig#moduleResolution): `Bundler` is the best option for if the code you're writing is meant to be bundled with a tool like Webpack, Rollup, Babel, SWC, or ESBuild.
- [`module`](https://www.typescriptlang.org/tsconfig#module): `ESNext` is the best option because it most closely mimics how bundlers treat modules.

### Running in the DOM

If your code runs in the DOM, you'll want these options.

```json
{
  "compilerOptions": {
    "lib": ["es2022", "dom", "dom.iterable"]
  }
}
```

- [`lib`](https://www.typescriptlang.org/tsconfig#lib): Tells TypeScript what built-in types to include. `es2022` is the best option for stability. `dom` and `dom.iterable` give you types for `window`, `document` etc.

### Not Running in the DOM

If your code _doesn't_ run in the DOM, you'll want `lib: ["es2022"]`.

```json
{
  "compilerOptions": {
    "lib": ["es2022"]
  }
}
```

These are the same as above, but without the `dom` and `dom.iterable` typings.

### Building for a Library

If you're building for a library, you'll want `declaration: true`.

```json
{
  "compilerOptions": {
    "declaration": true
  }
}
```

- [`declaration`](https://www.typescriptlang.org/tsconfig#declaration): Tells TypeScript to emit `.d.ts` files. This is needed so that libraries can get autocomplete on the `.js` files you're creating.

### Building for a Library in a Monorepo

If you're building for a library in a monorepo, you'll also want these options.

```json
{
  "compilerOptions": {
    "declaration": true,
    "composite": true,
    "sourceMap": true,
    "declarationMap": true
  }
}
```

- [`composite`](https://www.typescriptlang.org/tsconfig#composite): Tells TypeScript to emit `.tsbuildinfo` files. This tells TypeScript that your project is part of a monorepo, and also helps it to cache builds to run faster.
- [`sourceMap`](https://www.typescriptlang.org/tsconfig#sourceMap) and [`declarationMap`](https://www.typescriptlang.org/tsconfig#declarationMap): Tells TypeScript to emit source maps and declaration maps. These are needed so that when consumers of your libraries are debugging, they can jump to the original source code using go-to-definition.

## What Did I Miss?

Hopefully, I've given you a bit of inspiration for the next time you need to configure TypeScript.

Did I miss anything? Let me know by [pinging me on X](https://twitter.com/mattpocockuk).


Learn the essential TypeScript configuration options and create a concise tsconfig.json file for your projects with this helpful cheatsheet.

The TSConfig Cheat Sheet

A recent video by [Fireship](https://www.youtube.com/watch?v=5ChkQKUzDCs), entitled "Big projects are ditching TypeScript... why?" is getting a lot of traction.

So much so, that I'm now regularly getting questions like this:

> What do you think about the mass abandonment of TypeScript by big projects?

I think that Fireship's video contains a number of inaccuracies, and I'd like to address them here.

## Why Did Turbo 8 Drop TypeScript?

The video was released after DHH's announcement that [Turbo 8](https://world.hey.com/dhh/turbo-8-is-dropping-typescript-70165c01) is dropping TypeScript.

Fireship's video got this absolutely right. Turbo 8 has _fully_ dropped TypeScript - from their source code _and_ the compiled output.

DHH reasoned that the source code was [now easier to read](https://github.com/hotwired/turbo/pull/971#issuecomment-1708430006), and that contributors weren't consulted because "this is one of those debates where arguments aren't likely to move anyone's fundamental position". Predictably, the [PR to remove TypeScript](https://github.com/hotwired/turbo/pull/971) from Turbo was _not_ popular with both Turbo's users and contributors.

Fireship's video made it seem as if users of Turbo will still get a decent experience with TypeScript. This is not true. If Turbo chooses not to ship type definitions (which are automatically created from TS files) you'll no longer get autocomplete and type safety when importing it into TypeScript files. Rich Harris, creator of Svelte, memorably called this behavior "[user-hostile dickwaddery](https://twitter.com/Rich_Harris/status/1699490194565578882)".

Turbo could still choose to manually author these type definitions to help their users. But this would mean manually creating `.d.ts` files and shipping them. Given their stance, this seems unlikely.

## Why Did Svelte Drop TypeScript?

The video also mentions that Svelte "no longer uses TypeScript". Then, it goes on to clarify that Svelte is "getting most of the benefits of TypeScript by using JSDoc".

He's right! Svelte is still using TypeScript - just not in the way that most projects do.

To quote [Rich Harris again](https://news.ycombinator.com/item?id=35892250), they are "just moving type declarations from .ts files to .js files with JSDoc annotations". This way, Svelte is able to get the benefits of TypeScript without having to use `.ts` files. This means that "cmd-clicking on functions you import from Svelte [...] will take you to the actual source".

Svelte _still_ has a [`tsconfig.json` file](https://github.com/sveltejs/svelte/blob/effeb7abbac6d46455167b93c3b3767163d98753/packages/svelte/tsconfig.json). It still runs the [TypeScript type checker](https://github.com/sveltejs/svelte/blob/effeb7abbac6d46455167b93c3b3767163d98753/packages/svelte/package.json#L78C13-L78C29).

The only thing they've changed is the way they provide type information to the TypeScript compiler. By all reasonable definitions, they're still using TypeScript.

So, Fireship got this mostly right. But using this example in a video entitled "Big projects are ditching TypeScript" _is_ misleading.

## Why Did Drizzle Drop TypeScript?

This is perhaps the most misleading statement in the video. Drizzle, a popular TypeScript ORM, has not dropped TypeScript.

In the wake of DHH's announcement, Drizzle [tweeted](https://twitter.com/DrizzleORM/status/1699497381824201074) that "we're removing TypeScript from Drizzle". This was a reference, in jest, to DHH's post.

Unfortunately, Fireship [took this at face value](https://twitter.com/fireship_dev/status/1699871277752938572), and included it in his video as an example of a "big project" dropping TypeScript.

## Conclusions

Are big projects ditching TypeScript?

Turbo dropped TypeScript from their source code and compiled output. Svelte changed from `.ts` files to `.js` files, but is still using TypeScript. Drizzle were joking.

So, no. Big projects are not ditching TypeScript.


Big projects like Svelte and Drizzle are not abandoning TypeScript, despite some recent claims.

Are Big Projects Ditching TypeScript?

React's props model is extremely powerful. One of its most useful features is the ability to pass a component _as a prop_. This lets you create composable pieces of UI, helping to make your components more reusable.

The trouble is that this can often be difficult to type correctly. Let's fix that.

## Passing JSX as a Prop

One of the most flexible ways to pass a component as a prop is to get the component to receive JSX. Let's look at the example below:

```tsx twoslash
interface LayoutProps {
  nav: React.ReactNode;
  children: React.ReactNode;
}

const Layout = (props: LayoutProps) => {
  return (
    <>
      <nav>{props.nav}</nav>
      <main>{props.children}</main>
    </>
  );
};

<Layout nav={<h1>My Site</h1>}>
  <div>Hello!</div>
</Layout>;
```

Here, we're passing `<h1>My Site</h1>` to the `nav` prop, and `<div>Hello!</div>` to the `children` prop.

We're typing our props as `React.ReactNode`, which is a type that accepts any valid JSX. Note that we're not using `React.ReactElement` or `JSX.Element`. I cover why in [this article](https://www.totaltypescript.com/jsx-element-vs-react-reactnode).

## Passing a Component as a Prop

The second method is, instead of passing in JSX as a prop, we pass in an entire _component_ as a prop.

Some definitions here. JSX is the thing a component returns. `<Wrapper />` is JSX. `Wrapper` is the `component`.

The simplest way to type this in TypeScript is by using `React.ComponentType`:

```tsx twoslash
declare const UserIcon: React.ComponentType<{
  className?: string;
}>;

// ---cut---

const Row = (props: {
  icon: React.ComponentType<{
    className?: string;
  }>;
}) => {
  return (
    <div>
      <props.icon className="h-8 w-8" />
    </div>
  );
};

<Row icon={UserIcon} />;
```

Here, we're typing the `icon` prop as `React.ComponentType`. We're passing `{ className?: string }` to `React.ComponentType`, indicating that this is a component that can receive a `className` prop.

This basically says `icon` can be any component that can receive a `className` prop. This is a very flexible type, and it's easy to use.

## Passing a Native Tag as a Prop

Using `React.ElementType` lets you pass a native tag as a prop OR a custom component.

```tsx twoslash
declare const UserIcon: React.ComponentType<{
  className?: string;
}>;

// ---cut---
const Row = (props: {
  element: React.ElementType<{
    className?: string;
  }>;
}) => {
  return (
    <div>
      <props.element className="h-8 w-8" />
    </div>
  );
};

<Row element={"div"} />;
<Row element={UserIcon} />;
```

This is an extremely flexible definition and, again, very easy to use. We'll even get autocomplete on all the options we can pass to `element`.

For more information about `React.ComponentType` and `React.ElementType`, check out [this exercise](https://www.totaltypescript.com/workshops/advanced-react-with-typescript/types-deep-dive/understanding-react-s-elementtype-and-componenttype) in my Advanced React course.

## Passing Any Component as a Prop and Inferring Its Props

The final method is to be able to receive _any_ component and infer its props. This is very flexible but also extremely complex to type.

In my Advanced React and TypeScript course, I devote half of an entire section to [this topic](https://www.totaltypescript.com/workshops/advanced-react-with-typescript/advanced-patterns/the-as-prop-in-react).

The final solution I landed on is documented [here](https://github.com/total-typescript/react-typescript-tutorial/blob/main/src/08-advanced-patterns/72-as-prop-with-forward-ref.solution.tsx).

```tsx twoslash
// @errors: 2322
import {
  ComponentPropsWithRef,
  ElementType,
  ForwardedRef,
  forwardRef,
  useRef,
} from "react";

type FixedForwardRef = <T, P = {}>(
  render: (
    props: P,
    ref: React.Ref<T>
  ) => React.ReactNode
) => (
  props: P & React.RefAttributes<T>
) => React.ReactNode;

const fixedForwardRef =
  forwardRef as FixedForwardRef;

type DistributiveOmit<
  T,
  TOmitted extends PropertyKey
> = T extends any ? Omit<T, TOmitted> : never;

export const UnwrappedAnyComponent = <
  TAs extends ElementType
>(
  props: {
    as?: TAs;
  } & DistributiveOmit<
    ComponentPropsWithRef<
      ElementType extends TAs ? "a" : TAs
    >,
    "as"
  >,
  ref: ForwardedRef<any>
) => {
  const { as: Comp = "a", ...rest } = props;
  return <Comp {...rest} ref={ref}></Comp>;
};

// Can be passed 'as' prop but defaults to 'a'
const AnyComponent = fixedForwardRef(
  UnwrappedAnyComponent
);

// Defaulted to 'a'
<AnyComponent href="/" />;

// It's now a div, so can't be an href!
<AnyComponent as="div" href="/" />;
```

## Which Should I Choose?

If you're in a situation where you can choose either of the above approaches, I would lean towards passing JSX as a prop.

It's not only easy to type (`React.ReactNode`) but also very performance-friendly. JSX passed to a component as a prop is _not_ re-rendered when that parent component re-renders. This can be a huge performance boost.

But if you do need the other methods, then `React.ElementType` and `React.ComponentType` are both easy to type and easy to use.

If you can, stay away from using the open-ended 'as' prop. But if you do need it, then the description in [my advanced course](https://www.totaltypescript.com/workshops/advanced-react-with-typescript/advanced-patterns/the-as-prop-in-react) will help.


Learn different ways to pass a component as a prop in React: passing JSX, using React.ComponentType, and using React.ElementType.

How to Pass a Component as a Prop in React

You'll often find folks talking about "TypeScript Performance". They might say "my codebase feels slow" and that "TypeScript is making my editor slow".

What do they mean?

## What is TypeScript Performance?

TypeScript performance is a measure of how fast TypeScript can type-check your codebase. It's a measure of how quickly your editor can provide feedback on your code.

It's NOT a measure of how fast your code runs. TypeScript is a compile-time tool, not a runtime tool. Simply using TypeScript will not change the speed at which the emitted JavaScript runs - TypeScript doesn't do anything at runtime.

## What Does Bad TypeScript Performance Look Like?

When TypeScript performance is poor, you will notice:

- Your editor is slow to provide feedback on your code.
- Your editor is slow to autocomplete.
- Your builds take a long time to complete.

In other words, the things you do every day become slower and more painful.

## What Causes Bad TypeScript Performance?

TypeScript performance can be affected by several factors.

The first is scale. Simply put, the more code TypeScript needs to check at once, the slower it will run. However, scale is often less of a factor than you might think.

The second factor is the way you write your code. Using intersections instead of interfaces, utilizing project references, and employing return types judiciously are all useful ways to address TypeScript performance issues.

The [TypeScript Performance Wiki](https://github.com/microsoft/TypeScript/wiki/Performance) provides a great list of strategies you can use to improve your TypeScript performance.

## How Do You Measure TypeScript Performance?

You can use some `tsc` flags to measure your TypeScript performance.

Using `tsc --diagnostics` or `tsc --extendedDiagnostics` will provide you with information about how long it takes TypeScript to type-check your codebase.

By running `tsc --generateTrace ./outDir`, you can generate a trace file that can be opened in [Chrome's Trace Viewer](chrome://tracing) to see where TypeScript is spending its time.

[Aleksandra Sikora](https://twitter.com/aleksandrasays)'s [excellent talk at BeJS](https://www.youtube.com/watch?v=lJ63-j0OHG0) is a great resource to begin exploring this topic.


Learn about TypeScript performance and how it affects code type-checking speed, autocomplete, and build times in your editor.

Intro To TypeScript Performance

When you're working in a React app, declaring a type for your React props is likely going to be your most common TypeScript activity.

There's some debate over the best method for typing props. In this article, I'll show you the pros and cons of each method and give you my recommendation.

If you want to learn by doing, check out my free interactive course on [React and TypeScript](/tutorials/react-with-typescript/components/ensure-props-are-present-and-defined).

## The 3 Methods of Typing Props

### Inline Object Literals

Props can be declared using an inline object literal.

```tsx twoslash
import { ReactNode } from "react";

const Wrapper = (props: {
  children?: ReactNode;
}) => {
  return <div>{props.children}</div>;
};
```

Prop types can also be destructured, leading to a strange `{}: {}` syntax.

```tsx twoslash
import { ReactNode } from "react";

const Wrapper = ({
  children,
}: {
  children?: ReactNode;
}) => {
  return <div>{children}</div>;
};
```

### Type Aliases

Prop types can also be extracted to a type alias:

```tsx twoslash
import { ReactNode } from "react";

export type WrapperProps = {
  children?: ReactNode;
};

const Wrapper = (props: WrapperProps) => {
  return <div>{props.children}</div>;
};
```

Type aliases should always be exported along with the component - that way you can use them in other files if needed.

Props declared in a type alias can also be destructured:

```tsx twoslash
import { ReactNode } from "react";

export type WrapperProps = {
  children?: ReactNode;
};

// ---cut---

const Wrapper = ({ children }: WrapperProps) => {
  return <div>{children}</div>;
};
```

### Interfaces

Interfaces are another way to declare props:

```tsx twoslash
import { ReactNode } from "react";

export interface WrapperProps {
  children?: ReactNode;
}

const Wrapper = (props: WrapperProps) => {
  return <div>{props.children}</div>;
};
```

Just like type aliases, interfaces should always be exported so they can be reused later.

And, just like type aliases, interfaces can be destructured.

```tsx twoslash
import { ReactNode } from "react";

export interface WrapperProps {
  children?: ReactNode;
}

// ---cut---

const Wrapper = ({ children }: WrapperProps) => {
  return <div>{children}</div>;
};
```

Now that we've seen all the methods, let's look at all the pros and cons before we make our final decision.

## Use A React Props Code Snippet

The main benefit of inline object literals is speed. You can type your props quickly and move on.

The issue becomes that inline object literals will, eventually, need to be extracted out to a type.

So if you're writing a component, you should probably use a type alias or interface.

To get over this hurdle, I'd advise writing your own code snippets for type aliases and interfaces.

Here's a [code snippet](https://code.visualstudio.com/docs/editor/userdefinedsnippets) that will work in VSCode for creating your own components.

```json
{
  "component": {
    "prefix": "comp",
    "body": [
      "export interface $1Props {",
      "  $2",
      "}",
      "",
      "export const $1 = (props: $1Props) => {",
      "  return $3",
      "}"
    ]
  }
}
```

Autocompleting to `comp` will expand to a component with an interface, both exported.

## Interfaces over Intersections

My opinions on type aliases vs. interfaces are well documented in [this article](https://www.totaltypescript.com/type-vs-interface-which-should-you-use). In short, I prefer the `type` in general because of the 'declaration merging' property of the `interface`, which can confuse and frustrate beginners.

But there's one particular case where interfaces win over type aliases - that's in creating complex intersections of props.

Let's say you're creating a component that has all the props of `input` but needs to add a `label` prop. You'll need to extend from the `ComponentProps` type helper, described in [my article](https://www.totaltypescript.com/react-component-props-type-helper).

It is tempting to use a `type` alias:

```tsx twoslash
import { ComponentProps } from "react";

export type InputProps =
  ComponentProps<"input"> & {
    label: string;
  };

export function Input({
  label,
  ...props
}: InputProps) {
  return (
    <label>
      {label}
      <input {...props} />
    </label>
  );
}
```

But unfortunately, intersections used this way will, on the scale of a large codebase, slow TypeScript down.

Instead, you should use an interface, using `interface extends`:

```tsx twoslash
import { ComponentProps } from "react";

export interface InputProps
  extends ComponentProps<"input"> {
  label: string;
}
```

This advice comes from [TypeScript's performance wiki](https://github.com/microsoft/TypeScript/wiki/Performance), as well as a [PR from Sentry's codebase](https://github.com/getsentry/sentry/pull/30847/files) that sped up their type checking by removing these intersections in favor of interfaces.

So in situations where you're extending from other types, use interfaces.

## Final Thoughts

In general, you should use `interface` to declare your props. They're the most performant, and with a code snippet, they're fast to write.

If you've already got props declared using `type` or inline object literals, don't worry - this isn't worth a refactor.

But if your codebase starts to feel sluggish in your IDE, check for intersections in your props. If you find any, try to refactor them to `interface extends`.

When typing React props in a TypeScript app, using interfaces is recommended, especially when dealing with complex intersections of props.

Strongly Typing React Props with TypeScript

**TypeScript has become the most popular way to write JavaScript**. These days, if you want to get a job writing JavaScript, you'll need to know TypeScript.

But TypeScript is big. It's easy to end up in **tutorial hell**.

This **step-by-step guide** will help. I've built a set of dozens of questions that are designed to focus your learning on the most important parts of TypeScript.

With each question, I've provided a short explanation and a link to further resources.

By the end, you'll have learned enough TypeScript to feel productive, and get paid.

### Who Are You?

I'm **Matt Pocock**. I've worked at Vercel and Stately as a developer advocate. Now, I teach TypeScript full-time.

I'm on [YouTube](https://mattpocock.com/youtube) and [Twitter](https://mattpocock.com/twitter), and I've got a [Discord Server](https://mattpocock.com/discord). Come say hello!

### Interactive Tutorial

If you're looking for something more interactive, my free [Beginners TypeScript Tutorial](https://www.totaltypescript.com/tutorials/beginners-typescript) is a fantastic place to start. It's a great way to get straight into coding, if that's your vibe.

## Prerequisites

- You must know **JavaScript to a beginner level**. You'll need to know about variables, functions, objects, and all the basic parts of JS.
- You must know **how to use the command line**. You'll need to be able to run commands like `npm install` and `npm run build`.

## Instructions

- **Look at each question carefully**. Each question is designed to make you curious for more information at exactly the right time.
- **Make sure you understand the answer to the question** before moving on.
- If you get stuck, you can [tweet me](https://twitter.com/mattpocockuk) or ask a question in my [Discord Server](https://mattpocock.com/discord).

Best of luck!

---

# The Guide

## Basics

### 1. What Is TypeScript?

TypeScript is a set of tools that make writing JavaScript more pleasant.

The tools include:

- **The TypeScript Language**, written in `.ts` and `.tsx` files.
- **The TypeScript Compiler**, which turns TypeScript files into JavaScript files via the `tsc` CLI.
- **The TypeScript Language Server**, which powers the TypeScript experience in your IDE.

You can learn more on [TypeScript's Landing Page](https://www.typescriptlang.org/).

### 2. What Do You Need To Install To Use TypeScript?

You'll need to install [Node.js](https://nodejs.org/en) in order to use TypeScript to its fullest potential. Choose the LTS version.

You'll also need a code editor. I recommend [VSCode](https://code.visualstudio.com/download).

### 3. Why Would You Choose TypeScript Over JavaScript?

TypeScript makes your IDE more powerful. It gives you autocomplete, in-IDE errors, and many more powerful features.

```ts twoslash
// @errors: 2339
const user = {
  firstName: "Angela",
  lastName: "Davis",
  role: "Professor",
};

console.log(user.name);
```

It also means you're less likely to ship bugs. In 2019, Airbnb found that 38% of bugs they'd shipped to production could have been prevented by TypeScript. Watch [this talk](https://www.youtube.com/watch?v=P-J9Eg7hJwE) to learn more.

### 4. Does TypeScript Work In The Browser?

TypeScript uses some syntax which isn't in native JavaScript. For example, TypeScript has a `type` keyword, which JavaScript does not.

Because browsers only understand JavaScript, they can't run TypeScript files.

This means that to use TypeScript on the web, you need to turn TypeScript files into JavaScript files before you can send them to the browser.

### 5. How Do You Turn TypeScript Files Into JavaScript Files?

You can use the `tsc` CLI to compile TypeScript files into JavaScript files. You'll need to:

1. Install TypeScript on npm
2. Add a `tsconfig.json` file to your project (which tells TypeScript what to do)
3. Run `tsc` to compile your TypeScript files into JavaScript files

This [guide from VSCode](https://code.visualstudio.com/docs/typescript/typescript-compiling) will help you get started.

### 6. How Do You Use TypeScript To Build Modern Frontend Apps?

If you want to build a frontend application, you should use a frontend framework. Almost any modern framework you choose _will_ support TypeScript out of the box.

If you're not sure which to choose, I recommend [Vite](https://vitejs.dev/guide/) as a great place to start.

Frameworks like `Vite` take the responsibility of turning `.ts` files into `.js` files - as well as LOTS of other things.

This means you don't need to run `tsc` manually. Take a look at Vite's [getting started guide](https://vitejs.dev/guide/) to learn more.

### 7. How Do You Use TypeScript On CI?

Using TypeScript on CI is a great way to make sure your project is free of bugs. Once this is set up, your CI will fail if your project has any TypeScript errors.

[GitHub Actions](https://docs.github.com/en/actions/learn-github-actions) are a great way to try this out. But you can use TypeScript on any Linux-based, Windows-based, or MacOS-based CI. Anywhere Node.js runs, you can use TypeScript.

## Essential Types

Let's take a look at the essential parts of TypeScript's type system first.

Before you continue, I recommend you read the [Basics section](https://www.typescriptlang.org/docs/handbook/2/basic-types.html) of the TypeScript Handbook. This'll give you some good context for the rest of this section.

### 8. How Do You Type A Function's Parameters?

The first thing I recommend you learn is how to add types to a function's parameters.

This lets you add types to this `greet` function:

```ts twoslash
function greet(name: string) {
  console.log(
    "Hello, " + name.toUpperCase() + "!!"
  );
}
```

The `greet` function will then _only_ be able to accept a `string` as its first argument:

```ts twoslash
// @errors: 2345
function greet(name: string) {
  console.log(
    "Hello, " + name.toUpperCase() + "!!"
  );
}

// ---cut---

greet(42);
```

Learn more in the [Parameter Type Annotations](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#parameter-type-annotations) section of the TypeScript handbook.

### 9. What Are TypeScript's Basic Types?

TypeScript's basic types are `string`, `number`, `boolean`, and `symbol`. These represent the basic primitives that make up the JavaScript language.

```ts twoslash
let example1: string = "Hello World!";
let example2: number = 42;
let example3: boolean = true;
let example4: symbol = Symbol();
```

Here, we're also assigning those types to variables. This means that TypeScript will _only_ allow us to assign a `string` to `example1`, a `number` to `example2`, and so on.

```ts twoslash
// @errors: 2322
let example1: string = "Hello World!";
let example2: number = 42;
let example3: boolean = true;
let example4: symbol = Symbol();

// ---cut---

example1 = 42;
```

The TypeScript handbook has more information on [strings, numbers, and booleans](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#the-primitives-string-number-and-boolean). If you don't know what a Symbol is, head to [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol).

### 10. How Do You Type The Return Value Of A Function?

You can also type the return value of a function. This lets you add types to this `greet` function:

```ts twoslash
function greet(name: string): string {
  return "Hello, " + name.toUpperCase() + "!!";
}
```

This will ensure that the `greet` function _always_ returns a `string`:

```ts twoslash
// @errors: 2322
function greet(name: string): string {
  return 123;
}
```

You can learn more from the [TypeScript Handbook](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#return-type-annotations).

### 11. How Do You Type Objects?

Next, you should look at object types. These let you describe the shape of an object.

```ts twoslash
function printCoord(pt: {
  x: number;
  y: number;
}) {
  console.log(
    "The coordinate's x value is " + pt.x
  );
  console.log(
    "The coordinate's y value is " + pt.y
  );
}
printCoord({ x: 3, y: 7 });
```

These are described in [TypeScript's handbook](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#object-types).

You should also look at how to make [properties of objects optional](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#optional-properties).

### 12. How Do You Create A Reusable Type?

You might be thinking - what if I have a type that I want to use in multiple places? Do I have to write it out every time?

You can save types for later use using the `type` keyword:

```ts twoslash
type Point = {
  x: number;
  y: number;
};

function printCoord(pt: Point) {}
```

These are called [Type Aliases](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#type-aliases).

### 13. How Do You Type Arrays?

You can type arrays in two ways. Either using the `[]` syntax:

```ts twoslash
let example1: string[] = ["Hello World!"];
let example2: number[] = [42];
```

Or, by using the `Array<>` syntax:

```ts twoslash
let example1: Array<string> = ["Hello World!"];
let example2: Array<number> = [42];
```

The [TypeScript Handbook](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#arrays) section, as well as [my article comparing the two](https://www.totaltypescript.com/array-types-in-typescript), will help you learn more.

### 14. How Do You Type Tuples?

Tuples are arrays with a fixed length, where each element has a fixed type.

```ts twoslash
let example1: [string, number] = [
  "Hello World!",
  42,
];
```

You can learn more about them in the [TypeScript Handbook](https://www.typescriptlang.org/docs/handbook/2/objects.html#tuple-types).

### 15. How Do You Type Functions?

You can type functions using the `() => Type` syntax:

```ts twoslash
type MyFunction = () => string;

let example1: MyFunction = () => "Hello World!";
```

This is useful for typing callbacks passed to other functions:

```ts twoslash
function addEventListener(
  event: string,
  callback: () => void
) {
  document.addEventListener(event, callback);
}
```

You can learn more about [function types in the TypeScript Handbook](https://www.typescriptlang.org/docs/handbook/2/functions.html#function-type-expressions).

### 16. How Do You Type Sets and Maps?

You can type sets and maps using the `Set<Type>` and `Map<KeyType, ValueType>` syntax:

```ts twoslash
// @errors: 2345
let example1 = new Set<string>();

example1.add(42);

let example2 = new Map<string, number>();

example2.set("id", "abc");
```

This syntax lets you pass types to functions - an important idea that will come up later. Without these types, `Map` and `Set` wouldn't understand what types they should be.

```ts twoslash
let example1 = new Set();

// No error!
example1.add(42);

example1.add("abc");

let example2 = new Map();

// No error!
example2.set("id", "abc");
```

### 17. How Do You Type Async Functions?

You can type async functions by using the `Promise<>` syntax:

```ts twoslash
async function getGreeting(): Promise<string> {
  return "Hello World!";
}
```

If you don't use a `Promise`, TypeScript will error:

```ts twoslash
// @errors: 1064
async function getGreeting(): string {
  return "Hello World!";
}
```

## Unions And Narrowing

If you got this far, congratulations. You're doing great.

This guide is still incomplete! You can ping me at [@mattpocockuk](https://twitter.com/mattpocockuk) to give me a nudge to keep working on it.


Learn TypeScript in 2023 with this step-by-step guide. Understand the basics, essential types, unions, and narrowing techniques.

#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 1: Install TypeScript

Step 2: Add a `tsconfig.json` file

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

Step 4: Begin The Migration