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.

​

Конфигурация TypeScript

​

Обзор конфигурации

Выходные артефакты

Процесс сборки

Настройки tsconfig.json

Исходные файлы

src/core/ui/*.tsx
Примитивные компоненты

src/components/ui/*.tsx
Составные компоненты

src/layouts/*.tsx
Шаблоны макетов

src/core/variants/*.ts
Определения вариантов CVA

src/themes/**/*.tsx
Система тем

src/index.ts
Главная точка входа

rootDir: 'src'
Корневая директория исходников

outDir: './dist'
Выходная директория

target: 'ES2022'
Версия ECMAScript

module: 'ES2022'
Система модулей

declaration: true
Генерация .d.ts файлов

declarationDir: './dist'
Вывод определений типов

strict: true
Все строгие проверки включены

paths: @/* и @ui8kit/core
Сопоставления псевдонимов путей

tsc -p tsconfig.json
Компилятор TypeScript

tsc --noEmit
Только проверка типов

dist/index.js
Скомпилированный JavaScript

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

dist/components/**/*.js
Модули компонентов

dist/components/**/*.d.ts
Типы компонентов

​

Настройки целевой компиляции

​

Target: ES2022

• Top-level await
• Поля классов и приватные методы
• Блоки статической инициализации
• Свойство error cause
• Метод at() для массивов

​

Система модулей: ES2022

​

Разрешение модулей: Bundler

• Импорты без расширений (import { Button } from "./Button")
• Разрешение поля exports пакетов
• Условный экспорт для различных окружений
• Паттерны подпутей

​

Конфигурация системы типов

​

Строгий режим

• strictNullChecks: Null и undefined не присваиваются другим типам
• strictFunctionTypes: Параметры функций проверяются контравариантно
• strictBindCallApply: Проверка типов методов bind, call и apply
• strictPropertyInitialization: Свойства классов должны быть инициализированы
• noImplicitAny: Переменные должны иметь явные типы
• noImplicitThis: Выражения this требуют явного типа
• alwaysStrict: Разбор в строгом режиме и вывод "use strict"

​

Генерация объявлений

• Обеспечивают автодополнение в IDE для всех экспортируемых компонентов
• Предоставляют встроенную документацию из комментариев JSDoc
• Поддерживают проверку типов в TypeScript-проектах потребителей
• Поддерживают запись "types": "./dist/index.d.ts" в package.json32

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

Сгенерированные артефакты

Обработка компилятором

Исходный TypeScript

*.tsx компоненты
с JSDoc комментариями

*.ts утилиты
с экспортом типов

объявления interface
export type ButtonProps

tsc --declaration
Извлечение информации о типах

Разбор JSDoc комментариев
Конвертация в аннотации типов

dist/**/*.d.ts
Файлы объявлений типов

dist/index.d.ts
Главная точка входа типов

VSCode IntelliSense
Автодополнение свойств

tsc проверка типов
в проектах потребителей

IDE всплывающие подсказки
Показ документации

​

Составные проекты

• Позволяет выполнять более быстрые инкрементальные сборки
• Обеспечивает графы зависимостей между проектами TypeScript
• Поддерживает архитектуры monorepo, описанные в SUBMODULE_GUIDE.md

​

Конфигурация псевдонимов путей

// Из tsconfig.json:20-24
{
  "baseUrl": ".",
  "paths": {
    "@/*": ["./src/*"],
    "@ui8kit/core": ["./src/index"]
  }
}

​

Базовый URL

​

Сопоставления путей

​

Внутренние импорты: @/*

• import { Block } from "@/core/ui/Block"
• import { spacingVariants } from "@/core/variants/spacing"
• import { ThemeProvider } from "@/themes/providers/ThemeProvider"

​

Точка входа пакета: @ui8kit/core

• Примерах кода и документации
• Тестировании композиции компонентов
• Проверке публичной поверхности API

Разрешение модулей во время выполнения

Разрешенные пути к файлам

Разрешение путей (tsconfig.json paths)

Операторы импорта

import { Button } from '@/components/ui/Button'

import { Block } from '@/core/ui/Block'

import { spacingVariants } from '@/core/variants/spacing'

import { ThemeProvider } from '@ui8kit/core'

baseUrl: '.'
Ссылка на корень проекта

@/* → ./src/*
Сопоставление внутренних исходников

@ui8kit/core → ./src/index
Точка входа пакета

./src/components/ui/Button.tsx

./src/core/ui/Block.tsx

./src/core/variants/spacing.ts

./src/index.ts

dist/index.js
Скомпилированная точка входа пакета

dist/components/ui/Button.js
Скомпилированный компонент

​

Конфигурация выходных данных сборки

​

Корневая директория

src/
├── index.ts              → dist/index.js + dist/index.d.ts
├── core/
│   └── ui/
│       └── Block.tsx     → dist/core/ui/Block.js + dist/core/ui/Block.d.ts
└── components/
    └── ui/
        └── Button.tsx    → dist/components/ui/Button.js + dist/components/ui/Button.d.ts

​

Выходная директория

• Включена в NPM-пакет через "files": ["dist/**/*"] в package.json39-43
• Указана в "main": "./dist/index.js" в package.json31
• Исключена из системы контроля версий через .gitignore
• Генерируется скриптом npm run build в package.json22

​

Директория объявлений

• Упрощает распространение пакета (одна папка dist/)
• Соответствует ожиданиям потребителей относительно расположения типов
• Обеспечивает запись "types": "./dist/index.d.ts" в package.json32

​

Шаблоны включения и исключения

// Из tsconfig.json:2-3
{
  "include": ["./src"],
  "exclude": ["./lib", "./dist"]
}

​

Шаблон включения

• src/**/*.ts - Все файлы TypeScript
• src/**/*.tsx - Все файлы React-компонентов
• src/**/*.json - JSON-модули (через resolveJsonModule: true)

• Базовые примитивы в src/core/ui/
• Определения вариантов в src/core/variants/
• UI-компоненты в src/components/ui/
• Шаблоны макетов в src/layouts/
• Систему тем в src/themes/
• Метаданные реестра в src/registry.json

​

Шаблон исключения

• ./lib/ - Сгенерированные артефакты, такие как core-classes.json, описанные в Система сборки
• ./dist/ - Ранее скомпилированный вывод для избежания рекурсивной компиляции

​

Специальные опции компилятора

​

Типы среды выполнения Bun

• Проверку типов для специфичных API Bun
• Поддержку команд bun в скриптах, таких как bunx buildy-ui@latest scan в package.json26
• Разработку с быстрым транспилятором TypeScript от Bun

​

Разрешение JSON-модулей

// Импорт метаданных реестра с типами
import registry from "@/registry.json";

// TypeScript выводит тип из структуры JSON
const component = registry.registry.find(c => c.name === "button");

​

Совместимость с CommonJS

// Работает, даже если пакет использует module.exports
import cva from "class-variance-authority";

​

Проверка типов библиотек

• Значительно ускоряет компиляцию
• Избегает ошибок от несовместимых типов библиотек
• Фокусирует проверку типов на исходном коде проекта

​

Интеграция со скриптами сборки

Вывод/Проверка

Примененные настройки tsconfig.json

Режимы компилятора TypeScript

npm скрипты (package.json)

npm run build
tsc -p tsconfig.json

npm run type-check
tsc --noEmit

npm run lint
eslint src --ext .ts,.tsx

npm run lint:fix
eslint src --ext .ts,.tsx --fix

Полная компиляция
Генерация .js + .d.ts

Только проверка типов
Без выходных файлов

Все 20+ настроек
из tsconfig.json

Строгие проверки типов
strict: true

Генерация объявлений
declaration: true

Разрешение путей
@/* и @ui8kit/core

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

Ошибки типов сообщены
Код выхода 1 при ошибке

Ошибки ESLint
Стандарты кодирования

​

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

tsc -p tsconfig.json

1. Читает все настройки из tsconfig.json
2. Компилирует src/**/*.ts и src/**/*.tsx в dist/
3. Генерирует определения типов .d.ts в dist/
4. Применяет преобразования псевдонимов путей
5. Включает строгую проверку типов
6. Завершается с кодом 1, если обнаружены какие-либо ошибки типов

​

Скрипт проверки типов

tsc --noEmit

• Выполняет полную проверку типов без генерации файлов
• Проверяет типы в локальной разработке
• Работает быстрее, чем полная компиляция
• Полезен в CI/CD конвейерах перед развертыванием

​

Интеграция скрипта линтинга

eslint src --ext .ts,.tsx

• Понимание псевдонимов путей, определенных в tsconfig.json
• Разбор синтаксиса TypeScript (расширения .ts, .tsx)
• Доступ к информации о типах для продвинутых правил линтинга

​

Резюме

1. Цель компиляции: Модули ES2022 с разрешением, дружественным к бандлерам
2. Генерация типов: Полные файлы объявлений (.d.ts) для интеграции с IDE
3. Строгая проверка: Все опции строгого режима включены для безопасности типов
4. Псевдонимы путей: @/* для внутренних импортов, @ui8kit/core для ссылки на пакет
5. Структура вывода: Директория dist/, отражающая структуру src/
6. Поддержка JSON: Импорт метаданных реестра как типизированных модулей
7. Интеграция сборки: Скрипты для компиляции, проверки типов и линтинга