​

TypeScript Configuration

• package.json
• tsconfig.json

​

Configuration Overview

Output Artifacts

Build Process

tsconfig.json Settings

Source Files

src/core/ui/*.tsx
Primitive components

src/components/ui/*.tsx
Composite components

src/layouts/*.tsx
Layout templates

src/core/variants/*.ts
CVA variant definitions

src/themes/**/*.tsx
Theme system

src/index.ts
Main entry point

rootDir: 'src'
Source root directory

outDir: './dist'
Output directory

target: 'ES2022'
ECMAScript version

module: 'ES2022'
Module system

declaration: true
Generate .d.ts files

declarationDir: './dist'
Type definition output

strict: true
All strict checks enabled

paths: @/* and @ui8kit/core
Path alias mappings

tsc -p tsconfig.json
TypeScript compiler

tsc --noEmit
Type validation only

dist/index.js
Compiled JavaScript

dist/index.d.ts
Type definitions

dist/components/**/*.js
Component modules

dist/components/**/*.d.ts
Component types

​

Compilation Target Settings

​

Target: ES2022

• Top-level await
• Class fields and private methods
• Static initialization blocks
• Error cause property
• at() method for arrays

​

Module System: ES2022

​

Module Resolution: Bundler

• Extensionless imports (import { Button } from "./Button")
• Package exports field resolution
• Conditional exports for different environments
• Subpath patterns

​

Type System Configuration

​

Strict Mode

• strictNullChecks: Null and undefined are not assignable to other types
• strictFunctionTypes: Function parameters are checked contravariantly
• strictBindCallApply: Type-check bind, call, and apply methods
• strictPropertyInitialization: Class properties must be initialized
• noImplicitAny: Variables must have explicit types
• noImplicitThis: this expressions require explicit type
• alwaysStrict: Parse in strict mode and emit "use strict"

​

Declaration Generation

• Enable IDE autocomplete for all exported components
• Provide inline documentation from JSDoc comments
• Support type checking in consumer TypeScript projects
• Power the "types": "./dist/index.d.ts" entry in package.json32

Consumer Usage

Generated Artifacts

Compiler Processing

Source TypeScript

*.tsx components
with JSDoc comments

*.ts utilities
with type exports

interface declarations
export type ButtonProps

tsc --declaration
Extract type information

Parse JSDoc comments
Convert to type annotations

dist/**/*.d.ts
Type declaration files

dist/index.d.ts
Main type entry point

VSCode IntelliSense
Autocomplete props

tsc type checking
in consumer projects

IDE hover tooltips
Show documentation

​

Composite Projects

• Allow faster incremental builds
• Enable dependency graphs between TypeScript projects
• Support monorepo architectures documented in SUBMODULE_GUIDE.md

​

Path Alias Configuration

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

​

Base URL

​

Path Mappings

​

Internal Imports: @/*

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

​

Package Entry Point: @ui8kit/core

• Example code and documentation
• Testing component composition
• Verifying the public API surface

Runtime Module Resolution

Resolved File Paths

Path Resolution (tsconfig.json paths)

Import Statements

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

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

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

import { ThemeProvider } from '@ui8kit/core'

baseUrl: '.'
Project root reference

@/* → ./src/*
Internal source mapping

@ui8kit/core → ./src/index
Package entry point

./src/components/ui/Button.tsx

./src/core/ui/Block.tsx

./src/core/variants/spacing.ts

./src/index.ts

dist/index.js
Compiled package entry

dist/components/ui/Button.js
Compiled component

​

Build Output Configuration

​

Root Directory

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

​

Output Directory

• Included in NPM package via "files": ["dist/**/*"] in package.json39-43
• Referenced by "main": "./dist/index.js" in package.json31
• Excluded from version control via .gitignore
• Generated by the npm run build script in package.json22

​

Declaration Directory

• Simplifies package distribution (single dist/ folder)
• Matches consumer expectations for type locations
• Enables the "types": "./dist/index.d.ts" entry in package.json32

​

Include and Exclude Patterns

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

​

Include Pattern

• src/**/*.ts - All TypeScript files
• src/**/*.tsx - All React component files
• src/**/*.json - JSON modules (via resolveJsonModule: true)

• Core primitives in src/core/ui/
• Variant definitions in src/core/variants/
• UI components in src/components/ui/
• Layout templates in src/layouts/
• Theme system in src/themes/
• Registry metadata in src/registry.json

​

Exclude Pattern

• ./lib/ - Generated artifacts like core-classes.json documented in Build System
• ./dist/ - Previously compiled output to avoid recursive compilation

​

Special Compiler Options

​

Bun Runtime Types

• Type checking for Bun-specific APIs
• Support for bun commands in scripts like bunx buildy-ui@latest scan in package.json26
• Development with Bun’s fast TypeScript transpiler

​

JSON Module Resolution

// Import registry metadata with types
import registry from "@/registry.json";

// TypeScript infers type from JSON structure
const component = registry.registry.find(c => c.name === "button");

​

CommonJS Interoperability

// Works even if package uses module.exports
import cva from "class-variance-authority";

​

Library Type Checking

• Speeds up compilation significantly
• Avoids errors from incompatible library types
• Focuses type checking on project source code

​

Integration with Build Scripts

Output/Validation

tsconfig.json Settings Applied

TypeScript Compiler Modes

npm Scripts (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

Full Compilation
Generate .js + .d.ts

Type Validation Only
No output files

All 20+ settings
from tsconfig.json

Strict type checks
strict: true

Declaration generation
declaration: true

Path resolution
@/* and @ui8kit/core

dist/
Compiled modules

Type errors reported
Exit code 1 on error

ESLint errors
Coding standards

​

Build Script

tsc -p tsconfig.json

1. Reads all settings from tsconfig.json
2. Compiles src/**/*.ts and src/**/*.tsx to dist/
3. Generates .d.ts type definitions in dist/
4. Applies path alias transformations
5. Enables strict type checking
6. Exits with code 1 if any type errors are found

​

Type Check Script

tsc --noEmit

• Performs full type checking without generating files
• Validates types in local development
• Runs faster than full compilation
• Useful in CI/CD pipelines before deployment

​

Lint Script Integration

eslint src --ext .ts,.tsx

• Understanding path aliases defined in tsconfig.json
• Parsing TypeScript syntax (.ts, .tsx extensions)
• Accessing type information for advanced linting rules

​

Summary

1. Compilation Target: ES2022 modules with bundler-friendly resolution
2. Type Generation: Full declaration files (.d.ts) for IDE integration
3. Strict Checking: All strict mode options enabled for type safety
4. Path Aliases: @/* for internal imports, @ui8kit/core for package reference
5. Output Structure: dist/ directory mirroring src/ structure
6. JSON Support: Import registry metadata as typed modules
7. Build Integration: Scripts for compilation, type checking, and linting