Як налаштувати псевдоніми шляхів на кшталт @/ і чому однієї опції paths замало?

Замість import Button from '../../../components/Button.vue' зручно писати import Button from '@/components/Button.vue'. Для цього налаштовують псевдоніми шляхів.

У tsconfig.json:

{
  "compilerOptions": {
    "paths": {
      "@/*": ["./resources/js/*"]
    }
  }
}

Важлива зміна: раніше разом з paths вказували baseUrl. У TypeScript 6.0 його оголосили застарілим, а в TypeScript 7 - видалено (помилка «Option 'baseUrl' has been removed»). Шляхи в paths тепер пишуть відносно каталогу з tsconfig.json, з явним префіксом ./.

Чому однієї опції paths замало: вона лише каже компілятору, де шукати типи. Код вона не змінює - у зібраному JavaScript лишиться import ... from '@/components/Button.vue', і хтось має перетворити цей шлях на справжній.

Тому той самий псевдонім треба налаштувати в інструменті, що виконує чи збирає код:

• Vite - resolve.alias у vite.config.ts (у Laravel-проєктах @ часто вже налаштовано плагіном чи шаблоном стартового набору):

import { fileURLToPath, URL } from 'node:url';

export default defineConfig({
  resolve: {
    alias: { '@': fileURLToPath(new URL('./resources/js', import.meta.url)) },
  },
});

• Vitest - бере resolve.alias з конфігурації Vite;
• Node.js з вбудованим запуском TypeScript - не читає tsconfig.json і paths не підтримує. Альтернатива - subpath imports у package.json ("imports": { "#/*": "./src/*" }), які розуміють і Node.js, і TypeScript.

Типові помилки:

• псевдонім є в tsconfig.json, але не у збирачі - редактор задоволений, а збірка падає з «Failed to resolve import»;
• різні значення в двох місцях - редактор показує один файл, а в зібраному коді опиняється інший;
• paths у бібліотеці, яку публікують на npm, - у споживачів ці шляхи не працюватимуть; у пакетах краще imports/exports з package.json.

Докладніше в документації: Опція paths