## The Error

> Relative import paths need explicit file extensions in EcmaScript imports when '--moduleResolution' is 'node16' or 'nodenext'.

```ts
// Relative import paths need explicit file extensions in
// EcmaScript imports when '--moduleResolution' is 'node16'
// or 'nodenext'.

import { example } from "./foo";
```

---

## The Solution That Doesn't Work

Adding a `.ts` extension to the import path doesn't work, and results in the following error:

> An import path can only end with a '.ts' extension when 'allowImportingTsExtensions' is enabled.

```ts
// An import path can only end with a '.ts' extension when
// 'allowImportingTsExtensions' is enabled.

import { example } from "./foo.ts";
```

## The Solution

Add the `.js` extension to the import path.

```ts
import { example } from "./foo.js";
```

---

## Why Do We Need to Use JS File Extensions?

This error happens because you've specified `moduleResolution: NodeNext`. This tells TypeScript that you want your imports and exports to conform strictly to the Node spec.

The Node spec requires that you use `.js` file extensions for all imports and exports. This was decided so that a relative import path like `./foo.js` would work both in [Node and the browser](https://twitter.com/giltayar/status/1711669549760757997).

This also simplifies Node's module resolution strategy - Node doesn't have to do any guesswork to figure out what file to import. Thanks to [Gil Tayer](https://twitter.com/giltayar/status/1711670026464354460) for clarifying this for me.

## What if I don't want to use JS file extensions?

- Make sure you're using an external compiler, like esbuild, to compile your TypeScript code.
- Change your `tsconfig.json` to use `moduleResolution: Bundler` instead of `moduleResolution: NodeNext`.


When using '--moduleResolution' with the option 'nodenext', it is necessary to add explicit file extensions to relative import paths in EcmaScript imports.

Relative import paths need explicit file extensions in EcmaScript imports

Last week, the TypeScript team released TS 5.3.

As usual, I scanned the [announcement post](https://devblogs.microsoft.com/typescript/announcing-typescript-5-3/), but I quickly noticed something interesting.

One of the most important changes in TypeScript 5.3 wasn't mentioned in the release notes.

## Quick Code Sample

```ts twoslash
// This would error in 5.2, but is allowed in 5.3!
const array = ["a", "b", "c"] as const satisfies string[];

const returnWhatIPassIn = <const T extends any[]>(t: T) => {
  return t;
};

// result is any[] in TS 5.2, but ['a', 'b', 'c'] in 5.3
const result = returnWhatIPassIn(["a", "b", "c"]);
```

## Full Explanation

Working with readonly arrays in TS can be occasionally a bit of a pain.

Let's say you want to declare an array of routes as const.

This allows you to reuse the paths declared for a type.

```ts twoslash
declare const Home: any;
declare const About: any;

// ---cut---

const arrayOfRoutes = [
  { path: "/home", component: Home },
  { path: "/about", component: About },
] as const;

type Route = (typeof arrayOfRoutes)[number]["path"];
//    ^?
```

But what if you want to make sure that the `arrayOfRoutes` conforms to a certain type?

For that, you can use satisfies.

```ts twoslash
import React from "react";
declare const Home: any;
declare const About: any;

// ---cut---

const arrayOfRoutes = [
  { path: "/home", component: Home },
  { path: "/about", component: About },
] as const satisfies {
  path: string;
  component: React.FC;
}[];
// Type is 'readonly' and cannot be
// assigned to a mutable type
```

The only trouble is that in TypeScript 5.2, this would give an error! But... Why?

### Readonly Arrays vs Mutable Arrays

Well, it's because `arrayOfRoutes` is readonly, and you can't satisfy a mutable array with a readonly one.

So, the fix was to make the type we were satisfying a `readonly` array:

```ts twoslash
import React from "react";
declare const Home: any;
declare const About: any;

// ---cut---

const arrayOfRoutes = [
  { path: "/home", component: Home },
  { path: "/about", component: About },
] as const satisfies readonly {
  path: string;
  component: React.FC;
}[];

// No more error!
```

Now that we're using a readonly array, TypeScript is happy.

### Const Type Parameters

The same was true when using const type parameters, but even more pernicious.

In this position, `const` infers the thing passed into `T` as if it were `as const`.

But if you try to constrain it with an array, it doesn't work!

```ts twoslash
const returnWhatIPassIn = <const T extends any[]>(t: T) => {
  return t;
};

// result is any[] in TS 5.2!
const result = returnWhatIPassIn(["a", "b", "c"]);
```

Before TS 5.3, the fix was to add `readonly` to the type parameter:

```ts twoslash
const returnWhatIPassIn = <const T extends readonly any[]>(
  t: T
) => {
  return t;
};

// result is ['a', 'b', 'c']!
const result = returnWhatIPassIn(["a", "b", "c"]);
```

But this fix was hard to find and required some deep knowledge of how const type parameters worked.

### How TypeScript 5.3 Fixed It

Since 5.3, TypeScript has relaxed the rules around readonly arrays.

In these two situations, TypeScript now acts more helpfully.

The `satisfies` keyword now lets you pass in readonly arrays:

```ts twoslash
// This would error in 5.2, but is allowed in 5.3!
const array = ["a", "b", "c"] as const satisfies string[];
//    ^?
```

Const type parameters now infer the type passed in instead of defaulting to their constraints:

```ts twoslash
const returnWhatIPassIn = <const T extends any[]>(t: T) => {
  return t;
};

// result is any[] in TS 5.2, but ['a', 'b', 'c'] in 5.3
const result = returnWhatIPassIn(["a", "b", "c"]);
//    ^?
```

Note that there is a small difference! If you were to specify `readonly string[]` instead of `string[]`, you would get a readonly array back.

So you still need to specify readonly if you want a readonly array back.

```ts twoslash
// This would error in 5.2, but is allowed in 5.3!
const array = [
  //  ^?
  "a",
  "b",
  "c",
] as const satisfies readonly string[];

const returnWhatIPassIn = <const T extends readonly any[]>(
  t: T
) => {
  return t;
};

// result is any[] in TS 5.2, but ['a', 'b', 'c'] in 5.3
const result = returnWhatIPassIn(["a", "b", "c"]);
//    ^?
```

But this is a massive improvement, making both `const` type parameters and `satisfies` much easier to work with.

TypeScript - you gotta shout about these things! I'll be updating my course with this new behavior very soon.


TypeScript 5.3 introduces relaxed rules around readonly arrays and improvements in const type parameters.

The TypeScript 5.3 Feature They Didn't Tell You About

You have likely been sent this article because you asked someone a TypeScript question without providing a TypeScript playground.

Here's how to fix it.

1. Go to the [TypeScript Playground](https://www.typescriptlang.org/play).

2. Write your code in the editor. You can use libraries from `npm` (by simply importing them) if needed.

3. If your code doesn't fit in the editor, make your example simpler and smaller. The less code you ask someone to read, the more likely they are to help you.

4. Make sure you comment your code to show what you expect to happen.

```ts twoslash
// `a` should be inferred as a string, but it's a number...
const a = 1;
```

5. Consider using [`@ts-expect-error`](https://www.totaltypescript.com/concepts/how-to-use-ts-expect-error) to show where errors are expected in your code.

6. Make sure your code has NO errors except for the ones you expect to be there.

7. Save the playground. This will provide you with a URL that you can share with others.

8. If you asked the question on a platform that doesn't support sharing links (like YouTube comments), head to my [Discord Channel](https://totaltypescript.com/discord) to ask it.

## Why Not A Screenshot?

If you provided a screenshot to illustrate your problem, you might be over-estimating the skill of the developers you're asking for help.

Most developers can't just look at a screenshot and know exactly what the error is. They need to _play_ with code in order to understand what it does. For this, you need an IDE.

This is why the TypeScript playground is so useful - it provides shareable playgrounds that help facilitate collaboration.

## Why Not CodeSandbox/StackBlitz?

There are several tools out there that help provide a multi-file IDE with support for actually _running_ code.

These are great for sharing code, but they're not great for asking questions.

I've had many situations where people ask me a question using a StackBlitz/CodeSandbox link, and I have to spend 10 minutes trying to figure out what the problem is, or even _in which file_ it originates from.

So, I've learned to dread these links.

The TypeScript playground is a much better tool for asking questions, because it provides a single file with a single entry point.


Learn how to provide a TypeScript playground when asking for help with your TypeScript questions, making it easier for others to assist you.

"Sorry, I Need A TypeScript Playground In Order To Help"

## The Problem

When you're working with React and TypeScript, you'll often encounter this kind of error:

```tsx twoslash
// @errors: 7006
const onChange = (e) => {};

<input onChange={onChange} />;
```

It's not always clear what type you should give to the `e` inside your `onChange` function.

This can happen with `onClick`, `onSubmit`, or any of the other event handlers that DOM elements receive.

Luckily, there are several solutions:

## Solution 1: Hover, Then Type The Handler

The first solution is to hover over the type of the thing you're trying to pass in:

```tsx twoslash
const onChange = () => {};
// ---cut---

<input onChange={onChange} />;
//     ^?
```

As you can see, this outputs an astonishingly long type:

```txt
React.InputHTMLAttributes<HTMLInputElement>.onChange?:
  React.ChangeEventHandler<HTMLInputElement> | undefined
```

The part we want is this: `React.ChangeEventHandler<HTMLInputElement>`.

We can use that to type our `onChange` function:

```tsx twoslash
import React from "react";

const onChange: React.ChangeEventHandler<
  HTMLInputElement
> = (e) => {
  console.log(e);
};

<input onChange={onChange} />;
```

## Solution 2: Inline A Function, Then Type The Event

Sometimes, you don't want to type the entire function. You just want to type the event.

To extract the right event type, you need to do a slightly different dance.

First, create an inline function inside `onChange`.

```tsx twoslash
<input onChange={(e) => {}} />
```

Now you have access to `e`, you can hover over it and get the correct event type:

```tsx twoslash
<input onChange={(e) => {}} />
//                ^?
```

Finally, you can copy that type and use it to type your `onChange` function:

```tsx twoslash
import React from "react";

const onChange = (
  e: React.ChangeEvent<HTMLInputElement>
) => {
  console.log(e);
};

<input onChange={onChange} />;
```

This still feels slow, though. Is there a better way?

## Solution 3: Use `React.ComponentProps`

A way to speed this up would be to remove the step where we _check_ the type of the handler. It would be great to say 'I want this sort of handler type' and have TypeScript figure out the rest.

For this, we can use a type helper called `ComponentProps`, which I've [written about before](https://www.totaltypescript.com/react-component-props-type-helper).

```tsx twoslash
import React from "react";

const onChange: React.ComponentProps<"input">["onChange"] =
  (e) => {
    console.log(e);
  };

<input onChange={onChange} />;
```

By passing `input` to `ComponentProps`, we're telling TypeScript that we want the props for the `input` element.

Then, we grab the `onChange` property from those props, and use it to type our function.

Thanks to [Sebastien Lorber](https://twitter.com/sebastienlorber/status/1512420374201446405) for this tip!

## Solution 4: Use An `EventFrom` Helper

This is really nice, but we're still back to having to type the `onChange` function.

What if we want to extract just the event type?

We could use a combination of `Parameters`, `NonNullable`, and indexed access types to get there:

```tsx twoslash
import React from "react";

const onChange = (
  e: Parameters<
    NonNullable<React.ComponentProps<"input">["onChange"]>
  >[0]
) => {};
```

But that's far too much code to write.

Instead, let's imagine a type helper called `EventFor`:

```tsx twoslash
import React from "react";

type GetEventHandlers<
  T extends keyof JSX.IntrinsicElements
> = Extract<keyof JSX.IntrinsicElements[T], `on${string}`>;

/**
 * Provides the event type for a given element and handler.
 *
 * @example
 *
 * type MyEvent = EventFor<"input", "onChange">;
 */
export type EventFor<
  TElement extends keyof JSX.IntrinsicElements,
  THandler extends GetEventHandlers<TElement>
> = JSX.IntrinsicElements[TElement][THandler] extends
  | ((e: infer TEvent) => any)
  | undefined
  ? TEvent
  : never;

// ---cut---

const onChange = (e: EventFor<"input", "onChange">) => {
  console.log(e);
};

<input onChange={onChange} />;
```

This takes in the element type and the handler type, and returns the event type. You get autocomplete on each of the parameters, and you don't have to type the function.

The issue is, you need to keep a relatively large type helper in your codebase. Here's the code:

```ts twoslash
import React from "react";

// ---cut---

type GetEventHandlers<
  T extends keyof JSX.IntrinsicElements
> = Extract<keyof JSX.IntrinsicElements[T], `on${string}`>;

/**
 * Provides the event type for a given element and handler.
 *
 * @example
 *
 * type MyEvent = EventFor<"input", "onChange">;
 */
export type EventFor<
  TElement extends keyof JSX.IntrinsicElements,
  THandler extends GetEventHandlers<TElement>
> = JSX.IntrinsicElements[TElement][THandler] extends
  | ((e: infer TEvent) => any)
  | undefined
  ? TEvent
  : never;
```

## Which Solution Should You Use?

Personally, I prefer the `EventFor` solution. That might be because I came up with it, but here's why I like it:

- It's a single place you can go to get the event type for any element and handler
- You get autocomplete on the element and handler types
- I tend to prefer typing the event over typing the function - just muscle memory

But, if you don't want to keep a type helper around, the `ComponentProps` solution is a great alternative.


Learn how to work with events in React and TypeScript, from onClick to onSubmit.

Event Types in React and TypeScript

ESBuild is an extremely popular, extremely fast bundler. It's used by frameworks like Vite to bundle frontend code, but it can also be used to bundle Node.js code.

In this article, we'll learn how to use ESBuild to bundle a Node.js app.

We'll be using:

- [ESBuild](https://esbuild.github.io/) for bundling.
- [pnpm](https://pnpm.io/) for package management.
- [Node.js](https://nodejs.org/en/) for running our code.
- [TypeScript](https://www.typescriptlang.org/) for type safety.
- [ES Modules](https://nodejs.org/api/esm.html#modules-ecmascript-modules) as our module system.
- [npm-run-all](https://www.npmjs.com/package/npm-run-all) for running multiple scripts at once.

## 0. Understanding the Tools

To make our Node app ready for production, we will need a few things:

- A `lint` script to ensure type safety in our code.
- A `dev` script to run our code locally and check for TypeScript errors.
- A `build` script to bundle our code for production.
- A `start` script to run our bundled code in production.

## 1. Adding Our Config Files

### 1.1 `package.json`

Let's start with an empty repository and initialize it with `npm init -y`. This will create a `package.json` file.

### 1.2 `"type": "module"` in `package.json`

Next, add `"type": "module"` to the `package.json` file.

```json
{
  // ...other properties
  "type": "module"
  // ...other properties
}
```

This tells Node.js to use ES Modules instead of CommonJS modules.

### 1.3 Dependencies

If you don't have pnpm installed, [install it](https://pnpm.io/).

Next, let's install our dependencies:

```
pnpm add -D typescript esbuild @types/node npm-run-all
```

This will add `typescript`, `esbuild`, `@types/node`, and `npm-run-all` to our `package.json`.

This will also create a `pnpm-lock.yaml`. This file keeps track of the exact versions of our dependencies to make installation faster and more predictable.

### 1.4 TypeScript Config

Add a `tsconfig.json` file at the root of the project with the following configuration:

```json
{
  "compilerOptions": {
    /* Base Options: */
    "esModuleInterop": true,
    "skipLibCheck": true,
    "target": "es2022",
    "verbatimModuleSyntax": true,
    "allowJs": true,
    "resolveJsonModule": true,
    "moduleDetection": "force",
    /* Strictness */
    "strict": true,
    "noUncheckedIndexedAccess": true,
    /* If NOT transpiling with TypeScript: */
    "moduleResolution": "Bundler",
    "module": "ESNext",
    "noEmit": true,
    /* If your code doesn't run in the DOM: */
    "lib": ["es2022"]
  }
}
```

This configuration is drawn from Total TypeScript's [TSConfig Cheat Sheet](/tsconfig-cheat-sheet).

### 1.5 `.gitignore`

Add a `.gitignore` file with the following content:

```
node_modules
dist
```

`node_modules` contains all of the files we get from `npm`. `dist` contains all of the files we get from `esbuild`.

### 1.5 `src` folder

Create a `src` folder at the root of the project.

Inside the `src` folder, create an `index.ts` file with the following content:

```ts
console.log("Hello, world!");
```

## 2. Adding Our Scripts

### 2.1 `lint` script

Add a `lint` script to `package.json`:

```json
{
  // ...other properties
  "scripts": {
    "lint": "tsc"
  }
  // ...other properties
}
```

Try running this with `pnpm lint`. This will run TypeScript on your code, but it will not output any `.js` files.

Here, we are treating TypeScript as a linter to check the correctness of our code.

Try changing `console.log` to `console.lg` in `src/index.ts`. Then run `pnpm lint` again - it will report the incorrect code.

### 2.2 `build` script

Add a `build` script to `package.json`:

```json
{
  // ...other properties
  "scripts": {
    "build": "esbuild src/index.ts --bundle --platform=node --outfile=dist/index.js --format=esm"
  }
  // ...other properties
}
```

This script bundles our code using `esbuild`.

`--bundle` indicates that it should output only one file containing our entire bundle.

`--platform=node` indicates that it should bundle for Node.js.

`--outfile=dist/index.js` indicates that it should output the bundle to `dist/index.js`.

`--format=esm` indicates that it should use ES Modules for imports and exports.

Try running this with `pnpm build`. This will output a `dist/index.js` file.

### 2.3 `start` script

Add a `start` script to `package.json`:

```json
{
  // ...other properties
  "scripts": {
    "start": "node dist/index.js"
  }
  // ...other properties
}
```

This script runs our bundled code using Node.js.

Try running `pnpm build && pnpm start`. This will build our code and then run it.

You should see `Hello, world!` printed to the console.

### 2.3 `dev` script

The `dev` script will be the most complex. When we run it, we want to do several things at once:

- `tsc --watch` to check for TypeScript errors.
- `node --watch` to re-run our application when it changes.
- `esbuild --watch` to re-bundle our application when it changes.

For each of these, we will add a separate `npm` script, then run them all simultaneously using `npm-run-all`.

#### 2.3.1 `tsc --watch`

Add a `dev:tsc` script to our `package.json`:

```json
{
  // ...other properties
  "scripts": {
    "dev:tsc": "tsc --watch --preserveWatchOutput"
  }
  // ...other properties
}
```

The `--watch` flag tells TypeScript to re-run when the code changes.

The `--preserveWatchOutput` flag tells TypeScript not to clear the console output when it re-runs.

#### 2.3.2 `node --watch`

Add a `dev:node` script to our `package.json`:

```json
{
  // ...other properties
  "scripts": {
    "dev:node": "node --watch dist/index.js"
  }
  // ...other properties
}
```

#### 2.3.3 `esbuild --watch`

Add a `dev:esbuild` script to our `package.json`:

```json
{
  // ...other properties
  "scripts": {
    "dev:esbuild": "pnpm run build --watch"
  }
  // ...other properties
}
```

#### 2.3.4 `dev` script

Add a `dev` script to our `package.json`:

```json
{
  // ...other properties
  "scripts": {
    "dev": "run-p dev:*"
  }
  // ...other properties
}
```

This script runs all the scripts that start with `dev:` in parallel.

Try it out by running `pnpm dev`. You will see that type checking, bundling, and execution all happen simultaneously.

## 3. Final Thoughts

Congratulations! You now have a fully functional ESBuild/Node setup.

This setup can handle any Node.js code you throw at it, from `express` servers to Lambdas.

If you want to see a fully working example, check out [this repository](https://github.com/mattpocock/esbuild-node).


A step-by-step guide on setting up ESBuild to bundle a Node application.

Build a Node App With TypeScript & ESBuild

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",
    "allowJs": true,
    "resolveJsonModule": true,
    "moduleDetection": "force",
    "isolatedModules": true,

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

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

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

    /* AND if you're building for a library in a monorepo: */
    "composite": true,
    "declarationMap": 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"]
  }
}
```

## Full Explanation

### Base Options

Here are the base options I recommend for all projects.

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

- [`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.
- [`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.
- [`isolatedModules`](https://www.typescriptlang.org/tsconfig#isolatedModules): This option prevents a few TS features which are unsafe when treating modules as isolated files.

### 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.

#### 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.

### 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.

## 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 Error

#The Solution That Doesn't Work

#The Solution

#Why Do We Need to Use JS File Extensions?

#What if I don't want to use JS file extensions?

The Error

The Solution That Doesn't Work

The Solution

Why Do We Need to Use JS File Extensions?

What if I don't want to use JS file extensions?