If you’ve ever opened a tsconfig.json file, tweaked a setting, and prayed your build didn’t break, you’re not alone. TypeScript’s compiler settings can feel like a labyrinth of overlapping keywords. Four options in particular cause endless head-scratching:

• target
• module
• moduleResolution
• esModuleInterop

While they all sound like they’re doing the exact same thing (handling JavaScript modules), they actually control very distinct phases of compilation and module resolution.

Here is the ultimate mental model to untangle them once and for all.

The Quick Mental Model

To keep them straight, assign each setting a specific role in your build pipeline:

1. target: Modern Syntax vs. Legacy Compatibility

target dictates the version of JavaScript syntax TypeScript outputs when it strips out your types. It controls syntax features like async/await, arrow functions, classes, and optional chaining.

Important: target does not change how your import and export statements are written—unless your module setting depends on it!

Example

Imagine you write this TypeScript code:

const greet = (name: string) => {
  console.log(`Hello, ${name}?.length`);
};

• "target": "ES2020" → Outputs modern arrow functions and template literals as-is.

const greet = (name) => {
  console.log(`Hello, ${name}?.length`);
};

• "target": "ES5" → Transpiles everything down to old ES5-compatible code using regular functions and string concatenation.

var greet = function (name) {
  console.log("Hello, " + (name === null || name === void 0 ? void 0 : name.length));
};

2. module: The Module Format of the Output

While target controls JS syntax, module controls how files import and export other files in the generated .js output.

Common JS module systems include:

• CommonJS (CJS): Uses require() and module.exports (traditional Node.js).
• ES Modules (ESM): Uses import and export (modern browser & Node.js standard).

Example

Suppose your TypeScript code imports a helper:

import { add } from './math';
export const result = add(1, 2);

• "module": "CommonJS"

"use strict";
Object.defineProperty(exports, "__esModule", { value: true });
const math_1 = require("./math");
exports.result = (0, math_1.add)(1, 2);

• "module": "ESNext" (or ES2022)

import { add } from './math';
export const result = add(1, 2);

3. moduleResolution: How TS Finds Your Files

moduleResolution tells the TypeScript compiler the algorithm to use when searching for a module when you write import something from 'location'.

It doesn’t affect your compiled JS code at all. It strictly exists for compile-time type checking.

Common Values:

1. node10 (formerly node): Mimics older Node.js require() lookup behavior. Looks in node_modules, searches for index.js or package.json “main” fields.
2. node16 / nodenext: Built for modern Node.js which supports both ESM and CJS natively. It respects package.json "exports" fields and requires file extensions (like .js) in relative import paths!
3. bundler: Designed for apps using modern bundlers (Vite, Webpack, esbuild). It respects "exports" like node16, but relaxes rules like requiring explicit .js extensions in imports.

Example

import { helper } from './utils';

With node16, TypeScript will yell at you:

Relative import paths must end with an extension. You’d have to write ./utils.js (even though the source file is ./utils.ts).

With bundler, TypeScript lets ./utils pass without complaint because your bundler handles extension resolving for you.

4. esModuleInterop: Smoothing Over CJS & ESM Friction

Historically, CommonJS modules exported a single default value like this:

// lodash in CommonJS
module.exports = function () { /* ... */ };

ES Modules require explicit default exports (export default ...). When ESM code tries to import a CJS package, syntax friction happens:

// Standard ES Module spec requires this:
import React from 'react'; 

// But without esModuleInterop, TS forced you to do this for CJS libs:
import * as React from 'react';

Setting "esModuleInterop": true tells TypeScript to emit tiny helper functions in the JavaScript output so you can use standard import React from 'react' syntax seamlessly, even when importing legacy CommonJS modules.

Example

import express from 'express';

• "esModuleInterop": false → Fails compilation or runtime error because express exports via module.exports, not an ES default export.
• "esModuleInterop": true → TS wraps the require('express') in an __importDefault helper under the hood so your clean ES import default syntax just works!

Summary Checklist

When configuring your next project, ask yourself:

1. target: How old are the browsers or Node runtime I am deploying to? (e.g., ES2022)
2. module: What module system does my target runtime execute? (e.g., NodeNext for modern Node, ESNext for Vite/Frontend)
3. moduleResolution: Who is bundling or running my code? (e.g., bundler for Webpack/Vite, nodenext for pure Node)
4. esModuleInterop: Am I importing CommonJS libraries into an ESM project? (Set to true 99% of the time!)