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, включая точки входа, экспорты модулей, зависимости и настройку дистрибутива. Он объясняет, как конфигурация 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';
Файлы дистрибутива
Пакет распространяет только необходимые файлы, настроенные через поле 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
| Зависимость | Версия | Используется в | Назначение |
|---|
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 |
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
{
"peerDependencies": {
"react": "^18.0.0 || ^19.0.0",
"react-dom": "^18.0.0 || ^19.0.0"
}
}
Зависимости разработки
Зависимости разработки 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 |
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
Использует полную конфигурацию пакета:
Место установки: 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"
}
}
- Связывает 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
