tsconfig.json Key Options

// tsconfig.json (JSON format)
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "strict": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules"]
}

// tsconfig.json for a typical web app
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "lib": ["ES2020", "DOM"],
    "strict": true,
    "noEmit": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"]
    }
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

// tsconfig.json for Node.js (server-side)
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "outDir": "dist",
    "rootDir": "src",
    "declaration": true,
    "sourceMap": true,
    "strict": true
  },
  "include": ["src/**/*"]
}

target specifies the JavaScript version to output, and module specifies the module format. When using a browser-side bundler, moduleResolution: "bundler" (TypeScript 5.0+) is recommended. For Node.js, use module: "NodeNext" together with moduleResolution: "NodeNext".

For strict type-checking options, see strict mode options.

paths is used together with baseUrl to define import path shortcuts (aliases). As project folder hierarchies grow deeper, relative paths become long and hard to read.

import { db } from "../../../config/database";
import { logger } from "../../../lib/logger";

// With paths (@ acts as a shortcut)
import { db } from "@/config/database";
import { logger } from "@/lib/logger";

Configuration

Set baseUrl and paths in tsconfig.json.

tsconfig.json

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

With this configuration, @/config/database resolves to ./src/config/database. baseUrl sets the base directory for path resolution — "." refers to the project root (the folder containing tsconfig.json).

Caution: Path resolution after compilation

paths works correctly for TypeScript's type checking and editor autocompletion, but the compiled .js files do not automatically rewrite @/ to actual paths.

// TypeScript source (.ts)
import { db } from "@/config/database";

The same logic can also be written as:

// Compiled .js by tsc (@/ remains as-is)
const database_1 = require("@/config/database"); // Node.js cannot resolve this

You need a separate mechanism to resolve paths at runtime. Here are the main approaches — choose one that matches your project's runtime environment. Using multiple approaches at the same time can cause paths to be resolved twice, leading to unexpected errors.

Using tsc-alias

This tool scans compiled .js files and replaces @/ with relative paths. It is suited for projects that run directly on Node.js.

npm install --save-dev tsc-alias

Add tsc-alias to the build script in package.json. The order matters — it must run after tsc.

package.json

{
  "scripts": {
    "build": "tsc && tsc-alias",
    "build:watch": "concurrently \"tsc --watch\" \"tsc-alias --watch\""
  }
}

Running tsc-alias on the compiled .js files rewrites @/config/database to relative paths like ./config/database. The --watch option monitors file changes and rewrites automatically.

Using tsconfig-paths

This tool hooks into Node.js require() to resolve paths at runtime. It does not modify .js files — paths are resolved dynamically. It is suited for development with ts-node.

npm install --save-dev tsconfig-paths

To use it with ts-node, add the following to tsconfig.json.

tsconfig.json

{
  "ts-node": {
    "require": ["tsconfig-paths/register"]
  }
}

With this configuration, @/ is automatically resolved when running with ts-node.

ts-node src/index.ts

To run compiled .js files with node, register it with the -r option.

node -r tsconfig-paths/register dist/index.js

Using Vite (bundler)

When using a bundler like Vite or webpack, you need to configure aliases on the bundler side as well. Since the bundler resolves paths during the bundling stage, tsc-alias and tsconfig-paths are not needed.

npm install --save-dev vite

Add the following alias configuration to vite.config.ts.

vite.config.ts

import { defineConfig } from "vite";
import path from "path";

export default defineConfig({
  resolve: {
    alias: {
      "@": path.resolve(__dirname, "./src"),
    },
  },
});

For webpack, configure it in resolve.alias of webpack.config.js.

webpack.config.js

const path = require("path");

module.exports = {
  resolve: {
    alias: {
      "@": path.resolve(__dirname, "src"),
    },
  },
};

paths is a convenient feature, but since the TypeScript compiler itself does not resolve paths in the compiled output, additional configuration is required depending on your runtime environment.