Как настроить алиасы путей в tsconfig.json для TypeScript?

Проблема: TypeScript не понимает алиасы путей без дополнительной настройки

Вы всё делаете правильно в tsconfig.json, но TypeScript только проверяет типы и компилирует код — он не умеет автоматически преобразовывать алиасы в реальные пути для Node.js или сборщика (например, Webpack, Vite, ts-node). Ошибка "Cannot find module" возникает именно на этапе выполнения, потому что Node.js не знает, что @components/Header — это ./src/components/Header.

Вот полное решение для разных сценариев.

1. Если вы используете Node.js (чистый TypeScript с tsc)

Добавьте в tsconfig.json:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@components/*": ["src/components/*"],
      "@utils/*": ["src/utils/*"]
    },
    "outDir": "./dist",
    "rootDir": "./src"
  },
  "include": ["src/**/*"]
}

Но этого недостаточно. Вам нужно установить пакет tsconfig-paths и использовать его при запуске:

npm install --save-dev tsconfig-paths

Затем запускайте ваш код через:

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

Или, если используете ts-node для разработки:

ts-node -r tsconfig-paths/register src/index.ts

2. Если вы используете Webpack (React, Angular и т.д.)

Добавьте алиасы в конфигурацию Webpack:

// webpack.config.js
const path = require('path');

module.exports = {
  resolve: {
    alias: {
      '@components': path.resolve(__dirname, 'src/components/'),
      '@utils': path.resolve(__dirname, 'src/utils/')
    }
  }
};

Теперь Webpack будет понимать алиасы при сборке.

3. Если вы используете Vite (современный стандарт)

Добавьте в vite.config.ts:

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

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

4. Если вы используете Next.js

В tsconfig.json уже есть встроенная поддержка алиасов. Просто укажите:

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

Next.js автоматически подхватит эти настройки.

5. Для NestJS (аналогично Node.js)

Установите tsconfig-paths и добавьте в nest-cli.json:

{
  "compilerOptions": {
    "tsConfigPath": "tsconfig.build.json"
  }
}

И запускайте через nest start — NestJS сам подхватит tsconfig-paths.

Важные советы:

• Всегда используйте baseUrl — он задаёт корень для всех относительных алиасов. Обычно ставят "." (корень проекта).
• Проверьте, что пути в paths совпадают с реальной структурой папок. Ошибка в одной букве — и алиас не сработает.
• Для VS Code TypeScript сам подхватит алиасы из tsconfig.json, поэтому автодополнение будет работать. Если нет — перезагрузите окно (Ctrl+Shift+P → "Developer: Reload Window").
• Не путайте алиасы с baseUrl: baseUrl задаёт корень для всех путей, а paths — конкретные маппинги.

После настройки вы сможете писать красивые импорты:

import { Header } from '@components/Header';
import { formatDate } from '@utils/helpers';

Надеюсь, это поможет! Если остались вопросы — пишите.

{
  "compilerOptions": {
    "moduleResolution": "bundler",
    "baseUrl": ".",
    "paths": {
      "@components/*": ["src/components/*"],
      "@utils/*": ["src/utils/*"]
    }
  }
}