> ## Documentation Index
> Fetch the complete documentation index at: https://ui8kit.buildy.tw/llms.txt
> Use this file to discover all available pages before exploring further.

# Структура пакета

> Конфигурация пакета UI8Kit Core - точки входа, экспорт модулей, зависимости и настройка распространения для множественных методов интеграции

# Структура пакета

Этот документ описывает конфигурацию пакета `@ui8kit/core`, включая точки входа, экспорты модулей, зависимости и настройку дистрибутива. Он объясняет, как конфигурация package.json поддерживает множество методов интеграции (установка через NPM, установка отдельных компонентов через buildy-ui CLI, git submodules и прямое копирование исходного кода).

Для информации о процессе сборки, который генерирует файлы дистрибутива, см. [Система сборки](#3.6). Для деталей о системе реестра компонентов см. [Реестр компонентов](#3.7).

***

## Метаданные пакета

Пакет настроен как библиотека ES-модулей, нацеленная на современные среды JavaScript.

| Свойство | Значение | Назначение |
| - | - | - |
| `name` | `@ui8kit/core` | Идентификатор NPM-пакета с областью видимости |
| `version` | `0.1.8` | Семантическая версия (MAJOR.MINOR.PATCH) |
| `type` | `"module"` | Объявляет формат ES-модулей (не CommonJS) |
| `license` | `GPL-3.0` | Лицензия с открытым исходным кодом |
| `homepage` | `https://buildy.tw/` | Сайт документации и инструментов |
| `sideEffects` | `false` | Включает оптимизацию tree-shaking |

Объявление `type: "module"` [package.json8](https://github.com/ui8kit/core/blob/2afe2195/package.json#L8-L8) гарантирует, что все `.js` файлы обрабатываются как ES-модули, требуя явных расширений `.js` в операторах импорта. Флаг `sideEffects: false` [package.json30](https://github.com/ui8kit/core/blob/2afe2195/package.json#L30-L30) указывает, что пакет содержит чистые модули без побочных эффектов, позволяя сборщикам безопасно удалять неиспользуемый код.

**Источники:** [package.json1-30](https://github.com/ui8kit/core/blob/2afe2195/package.json#L1-L30)

***

## Точки входа и экспорты модулей

Пакет определяет единственную точку входа по умолчанию с разрешением в двух форматах:

```
{
  "main": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "import": "./dist/index.js",
      "types": "./dist/index.d.ts"
    }
  }
}
```

### Разрешение точки входа

```
Артефакты сборки

Файловая система

Разрешение пакета

Импорт потребителя

import { Button, Card } from '@ui8kit/core'

поле exports

точка входа '.'

условие import

условие types

dist/index.js
Код времени выполнения

dist/index.d.ts
Определения типов

TypeScript Compiler

src/index.tsx

src/components/ui/*

src/layouts/*

src/core/ui/*
```

Поле `main` [package.json31](https://github.com/ui8kit/core/blob/2afe2195/package.json#L31-L31) обеспечивает обратную совместимость для старых инструментов, в то время как поле `exports` [package.json33-37](https://github.com/ui8kit/core/blob/2afe2195/package.json#L33-L37) предоставляет современные условные экспорты. Условие `types` гарантирует, что TypeScript правильно разрешает определения типов для обеих стратегий разрешения.

Все компоненты экспортируются из единого barrel-файла в [src/index.tsx](https://github.com/ui8kit/core/blob/2afe2195/src/index.tsx) который компилируется в [dist/index.js](https://github.com/ui8kit/core/blob/2afe2195/dist/index.js) Это обеспечивает единую поверхность импорта:

```
// Все экспорты доступны из единой точки входа
import { Button, Card, Block, Box, DashLayout } from '@ui8kit/core';
```

**Источники:** [package.json31-37](https://github.com/ui8kit/core/blob/2afe2195/package.json#L31-L37)

***

## Файлы дистрибутива

Пакет распространяет только необходимые файлы, настроенные через поле `files`:

```
{
  "files": [
    "dist/**/*",
    "README.md",
    "LICENSE"
  ]
}
```

### Манифест дистрибутива

```
Исключенные файлы

Включенные файлы

Опубликованный пакет

исключен

исключен

исключены

исключены

исключен

@ui8kit/Unsupported markdown: link

dist/
Скомпилированный вывод

dist/index.js
Основная точка входа

dist/index.d.ts
Определения типов

dist/components/

dist/layouts/

dist/core/

dist/themes/

README.md
Документация

LICENSE
Условия GPL-3.0

src/
Исходный код

node_modules/

scripts/

tsconfig.json
eslint.config.js

src/registry.json
```

Массив `files` [package.json39-43](https://github.com/ui8kit/core/blob/2afe2195/package.json#L39-L43) явно включает только скомпилированный каталог `dist/` и файлы документации. Исходные файлы в `src/`, скрипты сборки и конфигурация разработки исключены из опубликованного пакета.

Файл `.gitignore` [.gitignore9-10](https://github.com/ui8kit/core/blob/2afe2195/.gitignore#L9-L10) исключает `dist/` из системы контроля версий, так как он содержит сгенерированные артефакты. Во время публикации в NPM процесс сборки генерирует `dist/` и включает его в tarball пакета.

**Источники:** [package.json39-43](https://github.com/ui8kit/core/blob/2afe2195/package.json#L39-L43) [.gitignore9-10](https://github.com/ui8kit/core/blob/2afe2195/.gitignore#L9-L10)

***

## Зависимости

Зависимости организованы в три категории в зависимости от того, когда и как они требуются:

### Зависимости времени выполнения

```
Использование компонентами

Зависимости времени выполнения

class-variance-authority@^0.7.1
Движок разрешения вариантов

clsx@^2.1.1
Условные имена классов

lucide-react@^0.525.0
Компоненты иконок

react-resizable-panels@^3.0.6
Панели DashLayout

tailwind-merge@^3.3.1
Дедупликация классов

Все компоненты
Используют CVA + CLSX + TWMerge

Компонент Sheet

Компонент Accordion

Компонент DashLayout
```

Зависимости времени выполнения [package.json48-54](https://github.com/ui8kit/core/blob/2afe2195/package.json#L48-L54) включены в пакет и устанавливаются автоматически:

| Зависимость | Версия | Используется в | Назначение |
| - | - | - | - |
| `class-variance-authority` | `^0.7.1` | Все компоненты | Система вариантов на основе CVA |
| `clsx` | `^2.1.1` | Все компоненты | Условное построение className |
| `lucide-react` | `^0.525.0` | Sheet, Accordion, DashLayout | Отрисовка иконок (X, ChevronDown и т.д.) |
| `react-resizable-panels` | `^3.0.6` | DashLayout | Изменяемые размеры боковых панелей |
| `tailwind-merge` | `^3.3.1` | Все компоненты | Дедупликация конфликтующих классов Tailwind |

Эти зависимости появляются в метаданных компонентов в [src/registry.json](https://github.com/ui8kit/core/blob/2afe2195/src/registry.json) Например, Sheet указывает `lucide-react` [src/registry.json54-55](https://github.com/ui8kit/core/blob/2afe2195/src/registry.json#L54-L55) а DashLayout указывает и `lucide-react`, и `react-resizable-panels` [src/registry.json266-267](https://github.com/ui8kit/core/blob/2afe2195/src/registry.json#L266-L267)

### Peer-зависимости

```
@ui8kit/core

Peer-зависимости

Приложение потребителя

устанавливает

устанавливает

устанавливает

использует из peer

использует из peer

package.json приложения

node_modules/

react@^18.0.0 || ^19.0.0

react-dom@^18.0.0 || ^19.0.0

@ui8kit/Unsupported markdown: link

Компоненты требуют React
```

Peer-зависимости [package.json55-58](https://github.com/ui8kit/core/blob/2afe2195/package.json#L55-L58) должны быть предоставлены потребляющим приложением:

```
{
  "peerDependencies": {
    "react": "^18.0.0 || ^19.0.0",
    "react-dom": "^18.0.0 || ^19.0.0"
  }
}
```

Диапазон версий поддерживает как React 18, так и 19, обеспечивая гибкость для приложений во время миграции на React 19. Библиотека не включает React в себя, избегая конфликтов версий и дублирования экземпляров React.

### Зависимости разработки

Зависимости разработки [package.json59-66](https://github.com/ui8kit/core/blob/2afe2195/package.json#L59-L66) используются только во время разработки и тестирования библиотеки:

| Зависимость | Версия | Назначение |
| - | - | - |
| `react` | `^19.1.0` | Разработка и тестирование |
| `react-dom` | `^19.1.0` | Разработка и тестирование |
| `bun-types` | `^1.1.29` | Типы для среды выполнения Bun |
| `typescript` | `^5.6.3` | Компиляция TypeScript |
| `@babel/parser` | `^7.28.4` | Скрипт извлечения CVA |
| `@babel/traverse` | `^7.28.4` | Скрипт извлечения CVA |

React и ReactDOM присутствуют как в `peerDependencies`, так и в `devDependencies`. Версии `devDependencies` используются для локальной разработки, в то время как `peerDependencies` объявляют требования совместимости для потребителей.

**Источники:** [package.json48-66](https://github.com/ui8kit/core/blob/2afe2195/package.json#L48-L66) [src/registry.json54-55](https://github.com/ui8kit/core/blob/2afe2195/src/registry.json#L54-L55) [src/registry.json266-267](https://github.com/ui8kit/core/blob/2afe2195/src/registry.json#L266-L267)

***

## Скрипты сборки

Секция `scripts` определяет команды для рабочих процессов разработки и публикации:

```
{
  "scripts": {
    "build": "tsc -p tsconfig.json",
    "type-check": "tsc --noEmit",
    "lint": "eslint src --ext .ts,.tsx",
    "lint:fix": "eslint src --ext .ts,.tsx --fix",
    "scan": "bunx buildy-ui@latest scan",
    "build:r": "bunx buildy-ui@latest build",
    "publish": "cd packages/registry && npm version patch && npm publish"
  }
}
```

### Поток скриптов сборки

```
Скрипты сборки

Скрипты разработки

Скрипты публикации

npm run publish

npm version patch

npm publish

Реестр NPM

Скрипты реестра

npm run scan
buildy-ui scan

src/registry.json

npm run build:r
buildy-ui build

npm run type-check
Проверка типов без вывода

npm run lint
Проверка качества кода

npm run lint:fix
Автоисправление проблем

npm run build
Компиляция TypeScript

tsc -p tsconfig.json

каталог dist/
```

| Скрипт | Команда | Назначение |
| - | - | - |
| `build` | `tsc -p tsconfig.json` | Компилирует TypeScript в `dist/` |
| `type-check` | `tsc --noEmit` | Проверяет типы без генерации файлов |
| `lint` | `eslint src --ext .ts,.tsx` | Проверяет качество кода |
| `lint:fix` | `eslint src --ext .ts,.tsx --fix` | Автоматически исправляет проблемы линтинга |
| `scan` | `bunx buildy-ui@latest scan` | Обновляет метаданные реестра компонентов |
| `build:r` | `bunx buildy-ui@latest build` | Собирает пакет реестра |
| `publish` | `cd packages/registry && npm version patch && npm publish` | Публикует в NPM |

Скрипт `build` [package.json22](https://github.com/ui8kit/core/blob/2afe2195/package.json#L22-L22) является основной командой компиляции, генерирующей ES2022-модули и объявления TypeScript в `dist/`. Скрипт `scan` [package.json26](https://github.com/ui8kit/core/blob/2afe2195/package.json#L26-L26) обновляет [src/registry.json](https://github.com/ui8kit/core/blob/2afe2195/src/registry.json) метаданными компонентов, обеспечивая установку отдельных компонентов через `npx buildy-ui add [component]`.

**Источники:** [package.json21-28](https://github.com/ui8kit/core/blob/2afe2195/package.json#L21-L28)

***

## Поддерживаемые методы интеграции

Структура пакета поддерживает четыре различных метода интеграции, каждый из которых использует разные аспекты конфигурации пакета:

### Матрица методов интеграции

```
Установленные артефакты

Используемая конфигурация пакета

Методы интеграции

Unsupported markdown: list
Unsupported markdown: list
Unsupported markdown: list
Unsupported markdown: list

main + exports
package.json:31-37

поле files
package.json:39-43

dependencies
package.json:48-54

peerDependencies
package.json:55-58

src/registry.json
Метаданные компонентов

массив items[]
18 компонентов

каталог src/
Исходный код TypeScript

repository.url
package.json:45

node_modules/@ui8kit/core/
dist/, README, LICENSE

components/ui/
Выбранные компоненты

packages/@ui8kit/core/
Полный исходный код

src/components/
Скопированный исходный код
```

### Метод 1: Полная установка через NPM

Использует полную конфигурацию пакета:

* Разрешает точки входа через поля `main` и `exports` [package.json31-37](https://github.com/ui8kit/core/blob/2afe2195/package.json#L31-L37)
* Устанавливает файлы, указанные в массиве `files` [package.json39-43](https://github.com/ui8kit/core/blob/2afe2195/package.json#L39-L43)
* Устанавливает все зависимости времени выполнения [package.json48-54](https://github.com/ui8kit/core/blob/2afe2195/package.json#L48-L54)
* Требует peer-зависимости [package.json55-58](https://github.com/ui8kit/core/blob/2afe2195/package.json#L55-L58)

Место установки: `node_modules/@ui8kit/core/`

### Метод 2: Установка по компонентам

Использует реестр компонентов:

* Читает метаданные компонентов из `src/registry.json` [src/registry.json3-276](https://github.com/ui8kit/core/blob/2afe2195/src/registry.json#L3-L276)
* Устанавливает только указанные файлы компонентов в `components/ui/` или `layouts/`
* Устанавливает зависимости, специфичные для компонента (например, `lucide-react` для Sheet)

Команда: `npx buildy-ui add [component]`

### Метод 3: Git Submodule

Использует URL репозитория:

* Клонирует репозиторий через `repository.url` [package.json45](https://github.com/ui8kit/core/blob/2afe2195/package.json#L45-L45)
* Предоставляет доступ к полному дереву исходного кода в `src/`
* Требует ручного управления зависимостями

Место установки: `packages/@ui8kit/core/` (типичный паттерн монорепозитория)

### Метод 4: Прямое копирование исходного кода

Использует исходные файлы напрямую:

* Копирует `src/components/` или конкретные компоненты
* Требует ручной установки зависимостей
* Позволяет делать кастомные модификации

Место установки: каталог `src/` приложения

**Источники:** [package.json31-58](https://github.com/ui8kit/core/blob/2afe2195/package.json#L31-L58) [src/registry.json1-281](https://github.com/ui8kit/core/blob/2afe2195/src/registry.json#L1-L281)

***

## Конфигурация репозитория

Поле `repository` обеспечивает обнаружение исходного кода и интеграции на основе git:

```
{
  "repository": {
    "url": "https://github.com/ui8kit/core.git",
    "type": "git"
  }
}
```

Эта конфигурация [package.json44-47](https://github.com/ui8kit/core/blob/2afe2195/package.json#L44-L47):

* Связывает NPM-пакет с GitHub-репозиторием
* Включает команду `npm repo` для открытия репозитория
* Поддерживает интеграцию git submodule через `git submodule add https://github.com/ui8kit/core.git`
* Обеспечивает видимость исходного кода для прозрачности (требование лицензии GPL-3.0)

**Источники:** [package.json44-47](https://github.com/ui8kit/core/blob/2afe2195/package.json#L44-L47)

***

## Конфигурация публикации

Секция `publishConfig` контролирует поведение публикации в NPM:

```
{
  "publishConfig": {
    "access": "public"
  }
}
```

Настройка `access: "public"` [package.json67-69](https://github.com/ui8kit/core/blob/2afe2195/package.json#L67-L69) требуется для того, чтобы пакеты с областью видимости (`@ui8kit/core`) были публично доступны в реестре NPM. Без этой конфигурации пакеты с областью видимости по умолчанию имеют приватный доступ.

**Источники:** [package.json67-69](https://github.com/ui8kit/core/blob/2afe2195/package.json#L67-L69)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.