Алиасы: alias и их использование в крупных проектах

В крупных проектах структура каталогов быстро усложняется. Появляются десятки директорий:

src/
├── components/
├── pages/
├── layouts/
├── services/
├── store/
├── hooks/
├── utils/
├── assets/
└── shared/

Без алиасов импорт модулей начинает выглядеть громоздко:

import Button from '../. ./. ./. ./components/ui/Button';
import api from '../. ./. ./services/api';
import formatDate from '../. ./. ./. ./. ./utils/date/formatDate';

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

  • ухудшается читаемость кода;
  • сложно перемещать файлы между директориями;
  • повышается вероятность ошибок в относительных путях;
  • усложняется рефакторинг;
  • снижается скорость навигации по проекту.

Механизм resolve.alias решает эту проблему, позволяя создавать псевдонимы для директорий и файлов.

Базовая настройка alias

Алиасы настраиваются внутри resolve.alias.

const path = require('path');

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

После этого можно использовать сокращённые пути:

import Header from '@/components/Header';
import api from '@/services/api';

Webpack заменяет @ на абсолютный путь к директории src.

Почему alias особенно важен в крупных проектах

В маленьком приложении относительные пути ещё терпимы. В монорепозиториях и enterprise-проектах они становятся серьёзной архитектурной проблемой.

Пример типичного импорта без алиасов:

import Modal from '../. ./. ./. ./. ./. ./shared/ui/Modal';

После перемещения файла путь может полностью сломаться.

С alias импорт становится стабильным:

import Modal from '@shared/ui/Modal';

Физическое расположение текущего файла перестаёт влиять на импорт.

Использование нескольких alias

В реальных проектах обычно создаётся целая система алиасов.

const path = require('path');

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

Использование:

import HomePage from '@pages/HomePage';
import Sidebar from '@components/navigation/Sidebar';
import authService from '@services/authService';

alias и абсолютные пути

alias фактически реализует систему абсолютных импортов.

Без alias:

../. ./. ./components/Button

С alias:

@components/Button

Такой подход:

  • уменьшает глубину импортов;
  • делает структуру проекта более предсказуемой;
  • улучшает читаемость;
  • упрощает перенос модулей.

Использование path.resolve

Для alias почти всегда применяется path.resolve.

const path = require('path');

Пример:

path.resolve(__dirname, 'src/components')

Результат:

/Users/project/src/components

Webpack получает абсолютный путь файловой системы.

Почему не стоит использовать относительные пути внутри alias

Неправильный вариант:

alias: {
  '@components': './src/components',
}

Проблемы:

  • зависимость от текущей рабочей директории;
  • нестабильность в CI/CD;
  • ошибки в различных окружениях;
  • сложности при запуске через IDE и инструменты сборки.

Правильный вариант:

alias: {
  '@components': path.resolve(__dirname, 'src/components'),
}

alias для отдельных файлов

Alias может указывать не только на директорию, но и на конкретный файл.

resolve: {
  alias: {
    '@config': path.resolve(__dirname, 'src/config/index.js'),
  },
}

Использование:

import config from '@config';

Переопределение библиотек через alias

Webpack позволяет заменять один модуль другим.

Пример:

resolve: {
  alias: {
    lodash: path.resolve(__dirname, 'src/custom-lodash.js'),
  },
}

Теперь:

import _ from 'lodash';

будет импортировать:

src/custom-lodash.js

Подмена тяжёлых библиотек облегчёнными аналогами

Популярная практика — замена библиотек для уменьшения bundle size.

Пример:

resolve: {
  alias: {
    react: 'preact/compat',
    'react-dom/test-utils': 'preact/test-utils',
    'react-dom': 'preact/compat',
  },
}

Такой подход позволяет существенно уменьшить размер сборки.

alias и архитектура проекта

Алиасы часто становятся частью архитектурных правил.

Пример структуры:

src/
├── app/
├── processes/
├── pages/
├── widgets/
├── features/
├── entities/
└── shared/

Настройка:

alias: {
  '@app': path.resolve(__dirname, 'src/app'),
  '@processes': path.resolve(__dirname, 'src/processes'),
  '@pages': path.resolve(__dirname, 'src/pages'),
  '@widgets': path.resolve(__dirname, 'src/widgets'),
  '@features': path.resolve(__dirname, 'src/features'),
  '@entities': path.resolve(__dirname, 'src/entities'),
  '@shared': path.resolve(__dirname, 'src/shared'),
}

Это особенно распространено в архитектуре Feature-Sliced Design.

Использование alias в monorepo

В монорепозиториях alias помогают организовывать связи между пакетами.

Структура:

packages/
├── ui/
├── core/
├── utils/
└── app/

Настройка:

alias: {
  '@ui': path.resolve(__dirname, '../ui/src'),
  '@core': path.resolve(__dirname, '../core/src'),
}

Импорт:

import Button from '@ui/Button';

alias и TypeScript

При использовании TypeScript настройка должна дублироваться в tsconfig.json.

Webpack:

resolve: {
  alias: {
    '@components': path.resolve(__dirname, 'src/components'),
  },
}

TypeScript:

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

Если этого не сделать:

  • Webpack будет работать;
  • TypeScript начнёт выдавать ошибки;
  • IDE потеряет автодополнение.

alias и Babel

При использовании Babel необходимо синхронизировать alias.

Установка:

npm install babel-plugin-module-resolver --save-dev

Настройка:

module.exports = {
  plugins: [
    [
      'module-resolver',
      {
        alias: {
          '@components': './src/components',
        },
      },
    ],
  ],
};

alias и Jest

Тестовая среда также должна понимать алиасы.

Настройка:

module.exports = {
  moduleNameMapper: {
    '^@components/(.*)$': '<rootDir>/src/components/$1',
  },
};

Без этого тесты не смогут находить модули.

alias и ESLint

ESLint требует отдельной настройки резолвинга.

Установка:

npm install eslint-import-resolver-webpack --save-dev

Настройка:

settings: {
  'import/resolver': {
    webpack: {
      config: 'webpack.config.js',
    },
  },
},

alias и VSCode

Для корректной работы автодополнения VSCode ориентируется на:

  • jsconfig.json;
  • tsconfig.json.

Пример:

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

Использование символа @

Наиболее популярный алиас — @.

alias: {
  '@': path.resolve(__dirname, 'src'),
}

Импорт:

import App from '@/App';

Причины популярности:

  • короткий синтаксис;
  • удобство набора;
  • компактные импорты;
  • визуальная узнаваемость.

Использование alias с окончанием $

Webpack поддерживает точное совпадение имени через $.

Пример:

alias: {
  react$: path.resolve(__dirname, 'src/custom-react.js'),
}

Теперь:

import React from 'react';

будет заменён.

Но:

import something from 'react/utils';

заменён не будет.

Приоритет alias

Alias имеет высокий приоритет при резолвинге модулей.

Webpack сначала проверяет:

  1. alias;
  2. обычный node_modules;
  3. относительные пути.

Пример:

alias: {
  utils: path.resolve(__dirname, 'src/utils'),
}

Даже если существует пакет utils в node_modules, Webpack выберет alias.

Опасности конфликтов alias

Плохая практика:

alias: {
  path: path.resolve(__dirname, 'src/path'),
}

Это может конфликтовать со встроенным Node.js модулем path.

Лучше использовать уникальные префиксы:

@path
@utils
@shared

Чрезмерное количество alias

Избыточное число алиасов ухудшает поддержку проекта.

Плохой пример:

alias: {
  '@a': ...,
  '@b': ...,
  '@c': ...,
  '@d': ...,
}

Разработчики перестают понимать структуру.

Хорошая практика:

  • использовать алиасы только для ключевых модулей;
  • строить их вокруг архитектуры;
  • избегать микроскопических alias.

alias и tree shaking

Сам по себе alias не влияет на tree shaking.

Но неправильная подмена модулей может нарушить оптимизацию.

Пример проблемы:

alias: {
  lodash: path.resolve(__dirname, 'src/lodash-wrapper.js'),
}

Если wrapper экспортирует всё содержимое библиотеки, размер bundle может увеличиться.

Использование alias в динамических импортов

Alias работают и в import().

const module = await import('@components/Modal');

Webpack корректно разрешит путь.

alias и code splitting

Alias полностью совместимы с:

  • lazy loading;
  • splitChunks;
  • dynamic import;
  • Module Federation.

Пример:

const AdminPage = lazy(() => import('@pages/AdminPage'));

resolve.modules vs alias

resolve.modules и alias решают разные задачи.

resolve.modules

Позволяет искать модули в дополнительных директориях.

resolve: {
  modules: [
    path.resolve(__dirname, 'src'),
    'node_modules',
  ],
}

Импорт:

import Button from 'components/Button';

alias

Создаёт явный псевдоним.

import Button from '@components/Button';

Alias считается более безопасным и предсказуемым.

Централизация alias

В крупных проектах список alias часто выносится в отдельный файл.

// aliases.js

const path = require('path');

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

Использование:

const aliases = require('./aliases');

module.exports = {
  resolve: {
    alias: aliases,
  },
};

Генерация alias автоматически

Иногда alias создаются автоматически на основе структуры директорий.

Пример:

const fs = require('fs');
const path = require('path');

const folders = fs.readdirSync('./src');

const aliases = folders.reduce((acc, folder) => {
  acc[`@${folder}`] = path.resolve(__dirname, 'src', folder);
  return acc;
}, {});

Подход удобен в огромных проектах, но ухудшает прозрачность конфигурации.

Практика именования alias

Распространённые соглашения:

@components
@shared
@core
@app
@pages
@features
@assets

Нежелательные варианты:

@c
@x
@tmp
@test1

Alias должны быть:

  • очевидными;
  • предсказуемыми;
  • архитектурно значимыми.

Alias в frontend-frameworks

Многие инструменты уже используют alias по умолчанию.

Vue CLI

@

указывает на src.

Nuxt

~
@

Vite

resolve: {
  alias: {
    '@': fileURLToPath(new URL('./src', import.meta.url)),
  },
}

Ошибки при использовании alias

Несогласованность конфигураций

Webpack настроен:

@components

TypeScript не настроен.

Результат:

  • сборка проходит;
  • IDE показывает ошибки.

Циклические зависимости

Alias иногда маскируют циклические импорты.

Пример:

@features/auth
↓
@shared/api
↓
@features/auth

Из-за абсолютных путей цикл может быть менее заметен.

Слишком глубокие alias

Плохой пример:

@components/forms/ui/buttons/base

Alias должен обозначать модуль верхнего уровня, а не превращаться в замену полного пути.

Рекомендуемая стратегия для крупных проектов

Оптимальный подход обычно включает:

@
@shared
@features
@entities
@pages
@widgets

Дополнительно:

  • единая конфигурация для Webpack, TS, Babel, Jest;
  • архитектурная документация;
  • запрет относительных импортов между крупными модулями;
  • использование ESLint для контроля импортов.

Пример полноценной конфигурации

const path = require('path');

module.exports = {
  resolve: {
    extensions: ['.js', '.ts', '.jsx', '.tsx'],
    
    alias: {
      '@': path.resolve(__dirname, 'src'),

      '@app': path.resolve(__dirname, 'src/app'),
      '@pages': path.resolve(__dirname, 'src/pages'),
      '@widgets': path.resolve(__dirname, 'src/widgets'),
      '@features': path.resolve(__dirname, 'src/features'),
      '@entities': path.resolve(__dirname, 'src/entities'),
      '@shared': path.resolve(__dirname, 'src/shared'),

      '@assets': path.resolve(__dirname, 'src/assets'),
      '@styles': path.resolve(__dirname, 'src/styles'),
      '@config': path.resolve(__dirname, 'src/config'),
    },
  },
};

Пример импортов:

import App from '@app/App';

import Header from '@widgets/Header';

import LoginForm from '@features/auth/LoginForm';

import UserCard from '@entities/user/UserCard';

import Button from '@shared/ui/Button';

import logo from '@assets/logo.svg';
Оглавление