Делаем import/require ясными и красивыми

Довольно часто в проектах встречается использование относительных import/require. Если это маленький проект, и подключается модуль из текущей папки, то это приемлемо, но при разрастании проекта и глубины вложенности папочной структуры без слез смотреть на это нельзя:

import { User } from '../../user/model';
import { Article } from '../../article/model';

import { Cache } from '../../../../cache';
import { MongoDB } from '../../../../mongodb';

Основные минусы относительных путей:

• Они плохо читаются и загрязняют код. Человеку требуются когнитивные усилия, чтобы интерпретировать эти ../../ в реальный путь. Гораздо проще читаются пути от корня к файлам.

• Редакторы кода не всегда корректно исправляют относительные пути при перемещении файла. А если редактор не смог добавить autoimport сущности из модуля при написании кода, то одна боль писать руками относительный import в более или менее развесистом проекте. Копирование import/require из другого файла тоже плохо работает, ибо если новый файл лежит на другом уровне вложенности, то придется во всех скопированных import/require добавлять/удалять ../../.

• При любом перемещении файла надо поменять не только пути в import/require в других файлах, которые его подключают, но и в самом перемещаемом файле меняются import/require (надо будет добавить/убрать лишние перемещения по каталогам). Это создает дополнительный «шум» в системе контроля версии, хотя по сути ничего не поменялось. С абсолютным путем этой проблемы бы не было.

В некоторых языках, как в Python, возможность писать импорты от корня проекта есть из коробки, но в JavaScript этого нет. К счастью, это довольно не сложно добавить.

Есть несколько способов решения проблемы:

Cимлинк

Создать симлинк в корне вашей системы, который ведет к вашему проекту, и использовать его для написания require/import.

// sudo ln -s /Users/mitya/project prj

// Вместо
const User = require('../../model/User');
// Можно будет использовать вот такую запись
const User = require('/prj/src/model/User');

Минус в том, что с симлинками могут быть «сюрпризы». Далеко не во всех операционках это легко. В современной MacOS есть определенные нюансы (надо использовать synthetic.conf). Кроме того, из-за странной работы с симлинками от корня на MacOS, компилятор typescript при компиляции проекта по симлинку от корня генерит что-то странное. Как в Windows, не знаю, но наверняка есть проблемы или ограничения. Судя по всему проблем не будет только на Linux. К минусам так же можно отнести то, что чисто гипотетически название симлинка может конфликтовать (например, ваш домашний и рабочий проект использует симлинк prj) и невозможность разложить копии проекта в разные папки и запустить без правки путей к модулям (тут виртуализация и контейнеризация поможет).

NODE_PATH

Другой вариант это добавить пути к вашим папкам в переменную окружения NODE_PATH. По умолчанию, она содержит пути для того, чтобы node js могла подключить модули из node_modules, но мы можем использовать ее в своих целях:

// Вместо
const User = require('../../model/User');
// Можно использовать вот такую запись
const User = require('src/model/User');

// при старте указываем пути, в которых node должна искать модули
// NODE_PATH=./ node src/app/main.js

// Для typescript необходимо добавить baseUrl, который должен совпадать с NODE_PATH
{
  "compilerOptions": {
    "baseUrl": "."
  }
}

Минус это то, что не все редакторы хорошо работают c NODE_PATH в плане перехода к файлу из объявления import/require. Но довольно давно появился способ получше.

Path aliases

Path aliases - это функционал для использования алиасов для путей внутри require/import.

// Вместо
const User = require('../../model/User');

// Можно использовать вот такую запись
const User = require('@/model/User');

Для того чтобы такая запись работала, нам потребуется модуль module-alias:

npm i module-alias -S

Для того чтобы module-alias мог сопоставить алиасы в реальный путь в файловой системе необходимо добавить следующую запись в package.json:

"_moduleAliases": {
    "@": "src"
  }

Затем в самом вверху файла, который является точкой сборки приложения, добавить import/require самого модуля:

// src/app/main.js
require('module-alias/register'); // import 'module-alias/register';

Другой вариант подключения это загружать модуль через командую строку:

node -r ./node_modules/module-alias/register src/app/main.js

Для того чтобы использовать path aliases в typescript необходимо добавить в tsconfig.json директиву path, в которой указать алиасы до исходников:

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

А папку для алиасов поменять в package.json на папку с итоговой сборкой, в нашем случае dist:

  "_moduleAliases": {
    "@": "dist"
  },

Теперь наши импорты с aлиасами должны работать:

node -r ./node_modules/module-alias/register dist/app/main.js

Если вы пишете бэкенд и для запуска проекта используете ts-node, то вам потребуется модуль ts-config-path для работы path aliases:

npm i tsconfig-paths -S;
npx ts-node -r tsconfig-paths/register src/app/main.ts;

Я же для запуска бэкенда на typescript использую tsx, он из коробки понимает path aliases:

npm i tsx -D;
npx tsx src/app/main.ts;

Алиасов можно создавать сколько душе угодно:

{
  "compilerOptions": {
    "paths": {
        "app/*": ["./src/app/*"],
        "config/*": ["./src/config/*"],
        "shared/*": ["./src/shared/*"],
        "cache/*": ["./src/cache/*"],
        "tests/*": ["./src/tests/*"]
    },
}

Подробнее про path alias можно почитать здесь и здесь. Используя path вместе с baseUrl можно организовать довольно интересные схемы подключения модулей из разных папок.

Теперь мы можем писать красивые и понятные import/require:

import { User } from '@component/user/model';
import { Article } from '@component/article/model';

import { Cache } from '@cache/cache';
import { MongoDB } from '@db/mongodb';