@astral/pack

Инструмент для сборки и релиза npm пакетов:

• Собирает пакеты в esm и cjs
  • Копирует статичные файлы
  • Генерирует package.json
• Semantic-release
  • Проверяет актуальную версию пакета
  • Создает релиз в gitlab и тэг в git

Installation

npm i --save @astral/utils

yarn add @astral/utils

Migration Guide v1 -> v2

Удалено свойство packageExports из конфигурации

v1

// pack.config.js
module.exports = defineConfig({
  packageExports: {
    './components/Button': {
      module: './components/Button/index.js',
      require: './node/components/Button/index.js',
      types: './components/Button/index.d.ts',
    },
  },
});

v2

Теперь экспорты задаются через исходный package.json:

{
  "exports": {
    "./components/Button": "./src/components/Button/index.ts",
    "./components/Input": "./src/components/Button/index.tsx"
  }
}

Строковые экспорты автоматически расширяются в полные объекты с учетом настроек format и lang из pack.config.js. Директория 'src' убирается из финального пути.

{
  "exports": {
    ".": {
      "module": "./index.js",
      "require": "./node/index.js",
      "types": "./index.d.ts",
      "default": "./index.js",
      "import": "./index.js"
    },
    "./components/Button": {
      "module": "./components/Button/index.js",
      "require": "./node/components/Button/index.js",
      "types": "./components/Button/index.d.ts",
      "default": "./components/Button/index.js",
      "import": "./components/Button/index.js"
    },
    "./components/Input": {
      "module": "./components/Input/index.js",
      "require": "./node/components/Input/index.js",
      "types": "./components/Input/index.d.ts",
      "default": "./components/Input/index.js",
      "import": "./components/Input/index.js"
    }
  }
}

Build

pack.config.js

const { defineConfig } = require('@astral/pack');

module.exports = defineConfig({
  target: 'web',
  // Сборка в esm и cjs
  format: ['esm', 'cjs'],
  tsConfigName: 'tsconfig.build.json',
  // Скопирует файлы в lib директорию
  copyStaticFiles: {
    filter: ['src/**/*.d.ts'],
    ignoreSrc: true,
  },
});

pack build --package-version=1.0.0

Build в связке с sematic-release

Запишет в .pack/versions.json новую версию пакета на основе анализа коммитов:

pack check-package-version

Заберет новую версию пакета из .pack/versions.json

pack build

Создание релиза в git и gitlab

pack create-release

Создаст git тэг и релиз в gitlab.

Exports

По-дефолту добавляет exports вида:

{
  "exports": {
    ".": {
      "module": "./index.js",
      "require": "./node/index.js",
      "types": "./index.d.ts",
      "default": "./index.js",
      "import": "./index.js"
    }
  }
}

Для добавления дополнительных exports укажите их в исходном package.json:

{
  "exports": {
    "./server": "./server/index.js",
    "./components/Button": "./src/components/Button/index.tsx"
  }
}

Строковые экспорты автоматически расширяются в полные объекты с учетом настроек format и lang. Директория 'src' убирается из финального пути.

{
  "exports": {
    ".": {
      "module": "./index.js",
      "require": "./node/index.js",
      "types": "./index.d.ts",
      "default": "./index.js",
      "import": "./index.js"
    },
    "./server": {
      "module": "./server/index.js",
      "require": "./node/server/index.js",
      "types": "./server/index.d.ts",
      "default": "./server/index.js",
      "import": "./server/index.js"
    },
    "./components/Button": {
      "module": "./components/Button/index.js",
      "require": "./node/components/Button/index.js",
      "types": "./components/Button/index.d.ts",
      "default": "./components/Button/index.js",
      "import": "./components/Button/index.js"
    }
  }
}

Если нужен полный контроль, можно указать объект напрямую:

{
  "exports": {
    "./custom": {
      "module": "./custom/special.js",
      "require": "./custom/special.cjs"
    }
  }
}

Настройка веток для semantic-release

По умолчанию semantic-release работает с ветками:

• main - основная ветка для релизов
• rc - prerelease ветка

Для переопределения веток используйте semanticRelease.releaseBranches:

module.exports = {
  semanticRelease: {
    repositoryUrl: 'https://git.astralnalog.ru/frontend.shared/pack',
    releaseBranches: [
      // Основная ветка
      'main',
      // Ветка rc будет публиковаться с тэгом 'rc'
      { name: 'rc', prerelease: true },
      // В ветке v4 будут публиковаться релизы с тэгом 'rc'
      { name: 'v4', prerelease: 'rc' },
      // Будут публиковаться релизы версий только для 3.x.x
      { name: 'v3', range: '3.x.x' },
    ],  
  },
};

Конфигурация releaseBranches полностью заменяет дефолтные ветки.

Подробнее в документации semantic-release.

Синхронный релиз пакетов

Для того чтобы deps пакета были синхронизированы с основным пакетом необходимо использовать semanticRelease.releaseGroup:

module.exports = {
  semanticRelease: {
    repositoryUrl: 'https://git.astralnalog.ru/frontend.shared/pack',
    releaseGroup: ['@astral/validations'],
  },
};

@astral/validations будет иметь после сборки ту же версию, что и основной пакет.

Удаление свойств package.json

Для удаления свойств package.json необходимо использовать omitPackageJsonProps:

module.exports = defineConfig({
  ...config,
  omitPackageJsonProps: ['engines'],
});

Результирующий package.json не будет содержать engines.

Переопределение свойств package.json

Для переопределения свойств package.json необходимо использовать overridePackageJson:

module.exports = defineConfig({
  ...config,
  overridePackageJson: {
    exports: {
      './base': './biome.json',
    }
  },
});

exports в результирующем package.json будет:

{
  "exports": {
    "./base": "./biome.json"
  }
}

Отправка уведомлений в telegram

Отправляет в telegram уведомление об успешном релизе пакета:

pack send-telegram-success-release --telegram-bot-token=$TELEGRAM_ASTRAL_UI_BOT_TOKEN --telegram-chat-id=$TELEGRAM_RELEASES_CHANNEL_ID

Пример сообщения:

🚀 Опубликован @astral/pack версии: 1.0.0

👀 Changelog:https://git.astralnalog.ru/frontend.shared/pack/-/releases/v1.0.0

Отправляет в telegram уведомление об ошибке релиза пакета:

pack send-telegram-fail-release --telegram-bot-token=$TELEGRAM_ASTRAL_UI_BOT_TOKEN --telegram-chat-id=$TELEGRAM_RELEASES_CHANNEL_ID --telegramPipelineUrl=$CI_PIPELINE_URL

Пример сообщения:

‼️Ошибка релиза @astral/pack
https://git.astralnalog.ru/frontend.shared/pack/-/pipelines/270356