Почему мне нужно указывать src в моем операторе импорта для пакета, который я публикую?

Вопрос или проблема

src
  /random
    /index.ts
  /index.ts
package.json
tsconfig.json
.gitignore

import {Random} from "@whiterook6/my-package";

console.log(Random.randomInt(1, 10));

Не удается найти модуль '@whiterook6/my-package' или его соответствующие объявления типов.ts(2307)

import {Random} from "@whiterook6/my-package/src";

console.log(Random.randomInt(1, 10));

import {Random, Logger} from "@whiterook6/my-package";

{
  "compilerOptions": {
    "target": "ESNext", // Укажите целевую версию ECMAScript
    "module": "ESNext", // Укажите стратегию генерации модульного кода
    "moduleResolution": "node", // Укажите стратегию разрешения модулей
    "declaration": true, // Генерировать файлы объявлений
    "emitDeclarationOnly": true, // Генерировать только файлы объявлений
    "outDir": "./src", // Перенаправить структуру вывода в каталог
    "rootDir": "./src", // Укажите корневой каталог входных файлов
    "strict": true, // Включите строгую проверку типов
    "esModuleInterop": true, // Включите совместимость с CommonJS и ES модулями
    "skipLibCheck": true, // Пропускать проверку типов файлов объявлений
    "forceConsistentCasingInFileNames": true // Обеспечить последовательный регистр в импортах
  },
  "include": [
    "src/**/*" // Включить все файлы в каталоге src
  ],
  "exclude": [
    "node_modules", // Исключить каталог node_modules
    "dist" // Исключить каталог dist
  ]
}

Ответ или решение

Почему нужно указывать src в инструкции импорта для публикации пакета?

Когда вы разрабатываете и публикуете пакет TypeScript в NPM, критически важно правильно настраивать структуру и параметры пакета. Ваша проблема заключается в том, что при импорте пакета без указания пути к каталогу src возникают ошибки компиляции. Давайте разберёмся, почему это происходит и как исправить ситуацию, чтобы пользователи могли импортировать ваш пакет без дополнительных сложностей.

Основные причины проблемы

1. Структура каталогов: Ваш текущий проект имеет структуру, в которой исходные файлы находятся в каталоге src. Это стандартная практика, но для того чтобы другие разработчики могли использовать ваш пакет, необходимо убедиться, что выходные (скомпилированные) файлы доступны в корневом каталоге.

2. Настройки TypeScript: Вы указали outDir и rootDir как ./src. Это означает, что скомпилированные файлы TypeScript будут помещены в ту же директорию, где находятся исходные файлы. Однако это не соответствует ожидаемой конфигурации для NPM-пакетов, где скомпилированные файлы обычно помещаются в отдельный каталог, например, dist.

3. Атрибут main в package.json: В вашем package.json отсутствует указание на файл, который будет загружен по умолчанию. Это важная часть, поскольку NPM будет искать файл, указанный в main, чтобы знать, откуда начинать. Если этот путь указывает на файл, лежащий в src, пользователям потребуется указывать src в своих импортах.

Как исправить ситуацию

Чтобы устранить возникшие проблемы и сделать ваш пакет более подходящим для использования, выполните следующие шаги:

1. Измените структуру вывода:
   Измените конфигурацию вашего tsconfig.json, чтобы компилируемые файлы находились в отдельной директории, например, dist. Вот как это сделать:

   {
    "compilerOptions": {
      // ... остальные параметры
      "outDir": "./dist", // Укажите директорию для скомпилированных файлов
      "rootDir": "./src"  // Оставьте корневую директорию для исходных файлов
    },
    "include": [
      "src/**/*"
    ]
   }

2. Обновите package.json:
   Убедитесь, что у вас есть правильный путь к точке входа в вашем package.json. Добавьте следующее:

   {
    "main": "dist/index.js", // основной файл для импорта
    "types": "dist/index.d.ts" // файл для типов, если он существует
   }

   Это позволит NPM знать, где искать код и типы, и разработчики смогут импортировать ваш пакет без дополнительных директорий.

3. Создайте файл сборки:
   Убедитесь, что в dist каталог скопированы все необходимые файлы после сборки. Например, в dist/index.js вы можете создать файл, который импортирует все необходимые функции из вашего кода.

4. Переполетите пакет:
   После внесения изменений, соберите свой проект заново и опубликуйте обновлённый пакет в NPM.

Заключение

Для успешного использования вашего TypeScript пакета крайне важно правильно организовать файлы и настройки. Убедившись в том, что пользователи не сталкиваются с подобными ошибками, вы улучшите опыт работы с вашим продуктом. Правильно настройка структуры проекта и конфигурация NPM позволит другим разработчикам легко импортировать ваш пакет, что положительно скажется на его популярности и использовании.