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

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

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

Пакет настроен как библиотека 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 гарантирует, что все .js файлы обрабатываются как ES-модули, требуя явных расширений .js в операторах импорта. Флаг sideEffects: false package.json30 указывает, что пакет содержит чистые модули без побочных эффектов, позволяя сборщикам безопасно удалять неиспользуемый код. Источники: package.json1-30

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

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

{
  "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 обеспечивает обратную совместимость для старых инструментов, в то время как поле exports package.json33-37 предоставляет современные условные экспорты. Условие types гарантирует, что TypeScript правильно разрешает определения типов для обеих стратегий разрешения. Все компоненты экспортируются из единого barrel-файла в src/index.tsx который компилируется в dist/index.js Это обеспечивает единую поверхность импорта:

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

Источники: package.json31-37

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

Пакет распространяет только необходимые файлы, настроенные через поле 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 явно включает только скомпилированный каталог dist/ и файлы документации. Исходные файлы в src/, скрипты сборки и конфигурация разработки исключены из опубликованного пакета. Файл .gitignore .gitignore9-10 исключает dist/ из системы контроля версий, так как он содержит сгенерированные артефакты. Во время публикации в NPM процесс сборки генерирует dist/ и включает его в tarball пакета. Источники: package.json39-43 .gitignore9-10

Зависимости

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

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

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

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

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 включены в пакет и устанавливаются автоматически:

Зависимость	Версия	Используется в	Назначение
`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 Например, Sheet указывает lucide-react src/registry.json54-55 а DashLayout указывает и lucide-react, и react-resizable-panels src/registry.json266-267

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 должны быть предоставлены потребляющим приложением:

{
  "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 используются только во время разработки и тестирования библиотеки:

Зависимость	Версия	Назначение
`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 src/registry.json54-55 src/registry.json266-267

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

Секция 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 является основной командой компиляции, генерирующей ES2022-модули и объявления TypeScript в dist/. Скрипт scan package.json26 обновляет src/registry.json метаданными компонентов, обеспечивая установку отдельных компонентов через npx buildy-ui add [component]. Источники: package.json21-28

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

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

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

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

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

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

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
Устанавливает файлы, указанные в массиве files package.json39-43
Устанавливает все зависимости времени выполнения package.json48-54
Требует peer-зависимости package.json55-58

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

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

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

Читает метаданные компонентов из src/registry.json src/registry.json3-276
Устанавливает только указанные файлы компонентов в components/ui/ или layouts/
Устанавливает зависимости, специфичные для компонента (например, lucide-react для Sheet)

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

Метод 3: Git Submodule

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

Клонирует репозиторий через repository.url package.json45
Предоставляет доступ к полному дереву исходного кода в src/
Требует ручного управления зависимостями

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

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

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

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

Место установки: каталог src/ приложения Источники: package.json31-58 src/registry.json1-281

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

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

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

Эта конфигурация package.json44-47:

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

Источники: package.json44-47

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

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

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

Настройка access: "public" package.json67-69 требуется для того, чтобы пакеты с областью видимости (@ui8kit/core) были публично доступны в реестре NPM. Без этой конфигурации пакеты с областью видимости по умолчанию имеют приватный доступ. Источники: package.json67-69

Getting started

Architecture

Components

Development Guide

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

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

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

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

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

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

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

Зависимости

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

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

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

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

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

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

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

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

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

Метод 3: Git Submodule

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

​Метод 3: Git Submodule

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

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

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

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

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

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

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

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

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

Зависимости

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

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

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

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

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

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

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

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

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

Метод 3: Git Submodule

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

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

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