TypeScript Configuration

Relevant source files

This document provides a detailed explanation of the TypeScript configuration in @ui8kit/core, covering compilation settings, type generation, path aliases, and module resolution. The configuration is defined in tsconfig.json1-26 and integrates with the build system documented in Build System. For information about the distribution artifacts generated by TypeScript compilation, see Package Structure. For details on how types are used in component APIs, see API Reference.

Configuration Overview

The TypeScript configuration serves three primary functions: compiling source code from src/ to ES2022 modules in dist/, generating type declaration files (.d.ts) for IDE autocomplete and type checking, and establishing path aliases for clean imports. Diagram: TypeScript Compilation Pipeline

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

Sources: tsconfig.json1-26 package.json22-25

Compilation Target Settings

The configuration targets modern JavaScript environments with ES2022 output, avoiding transpilation of recent language features while maintaining broad compatibility. Compilation Settings Table

Setting	Value	Purpose	Line Reference
`target`	`ES2022`	Compile to ECMAScript 2022 syntax	tsconfig.json5
`module`	`ES2022`	Use ES2022 module system	tsconfig.json6
`lib`	`["DOM", "ESNext", "ES2022"]`	Include DOM APIs and latest JavaScript features	tsconfig.json14
`jsx`	`react-jsx`	Use React 17+ automatic JSX runtime	tsconfig.json15
`moduleResolution`	`Bundler`	Modern bundler-compatible resolution	tsconfig.json7

Target: ES2022

The target: "ES2022" setting tsconfig.json5 compiles TypeScript to ECMAScript 2022, which includes:

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

This assumes consumers use modern browsers or Node.js 16+ environments.

Module System: ES2022

The module: "ES2022" setting tsconfig.json6 generates ES modules with .js extensions, enabling tree-shaking in consumer applications. This aligns with the "type": "module" declaration in package.json8

Module Resolution: Bundler

The moduleResolution: "Bundler" setting tsconfig.json7 uses bundler-specific resolution that supports:

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

This works seamlessly with modern bundlers like Vite, Webpack 5, and esbuild. Sources: tsconfig.json5-7 tsconfig.json14-15 package.json8

Type System Configuration

The configuration enables all strict type checking options and generates declaration files for IDE integration. Type System Settings Table

Setting	Value	Purpose	Line Reference
`strict`	`true`	Enable all strict type checks	tsconfig.json8
`declaration`	`true`	Generate `.d.ts` type declarations	tsconfig.json17
`declarationDir`	`./dist`	Output directory for type definitions	tsconfig.json18
`composite`	`true`	Enable project references	tsconfig.json16
`skipLibCheck`	`true`	Skip type checking of declaration files	tsconfig.json10
`esModuleInterop`	`true`	Enable CommonJS/ES module interoperability	tsconfig.json9

Strict Mode

The strict: true flag tsconfig.json8 enables all strict type checking options:

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"

This prevents common errors and ensures type safety across the component library.

Declaration Generation

The declaration: true setting tsconfig.json17 generates .d.ts files alongside compiled JavaScript. These type definitions:

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

Diagram: Type Definition Generation Flow

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

The composite: true flag tsconfig.json16 enables TypeScript project references, which:

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

Sources: tsconfig.json8-10 tsconfig.json16-18 package.json32

Path Alias Configuration

Path aliases enable clean imports using @/ prefix and @ui8kit/core package reference. Path Alias Settings

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

Base URL

The baseUrl: "." setting tsconfig.json20 establishes the project root as the base for all non-relative imports. This enables path resolution relative to the repository root.

Path Mappings

The paths object tsconfig.json21-24 defines two alias patterns: Alias Table

Alias Pattern	Resolves To	Usage Example	Purpose
`@/*`	`./src/*`	`import { Button } from "@/components/ui/Button"`	Internal source imports
`@ui8kit/core`	`./src/index`	`import { Button } from "@ui8kit/core"`	Main package entry point

Internal Imports: `@/*`

The @/* alias maps to ./src/* tsconfig.json22 enabling imports like:

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

This eliminates brittle relative paths (../../../core/ui/Block) and makes refactoring safer.

Package Entry Point: `@ui8kit/core`

The @ui8kit/core alias maps to ./src/index tsconfig.json23 allowing internal files to import from the package as consumers would. This is useful in:

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

Diagram: Path Resolution Flow

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

Sources: tsconfig.json20-24

Build Output Configuration

The configuration controls where compiled files and type definitions are written. Output Settings Table

Setting	Value	Purpose	Line Reference
`rootDir`	`src`	Source directory root	tsconfig.json13
`outDir`	`./dist`	Compiled JavaScript output	tsconfig.json19
`declarationDir`	`./dist`	Type definition output	tsconfig.json18

Root Directory

The rootDir: "src" setting tsconfig.json13 establishes src/ as the root for compilation. This ensures the output directory structure mirrors the source:

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

The outDir: "./dist" setting tsconfig.json19 writes compiled JavaScript to dist/. This directory is:

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

The declarationDir: "./dist" setting tsconfig.json18 writes .d.ts files alongside .js files in the same directory structure. This colocation:

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

Sources: tsconfig.json13 tsconfig.json18-19 package.json31-32 package.json39-43

Include and Exclude Patterns

The configuration specifies which files to compile and which to ignore. File Pattern Settings

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

Include Pattern

The include: ["./src"] setting tsconfig.json2 compiles all TypeScript files within the src/ directory:

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

This captures:

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

The exclude: ["./lib", "./dist"] setting tsconfig.json3 prevents compilation of:

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

Sources: tsconfig.json2-3

Special Compiler Options

Several additional options configure TypeScript’s behavior for specific use cases. Special Options Table

Setting	Value	Purpose	Line Reference
`types`	`["bun-types"]`	Include Bun runtime types	tsconfig.json11
`resolveJsonModule`	`true`	Allow importing JSON files	tsconfig.json12
`esModuleInterop`	`true`	Enable CommonJS interop	tsconfig.json9
`skipLibCheck`	`true`	Skip library type checking	tsconfig.json10
`sideEffects`	`false` (package.json)	Enable tree-shaking	package.json30

Bun Runtime Types

The types: ["bun-types"] setting tsconfig.json11 includes type definitions for the Bun runtime. This enables:

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

The bun-types dependency is declared in package.json62

JSON Module Resolution

The resolveJsonModule: true setting tsconfig.json12 allows importing JSON files as typed modules:

// 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");

This is used to import src/registry.json throughout the codebase, as documented in Component Registry.

CommonJS Interoperability

The esModuleInterop: true setting tsconfig.json9 enables seamless imports of CommonJS modules in ES module syntax:

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

This is essential for compatibility with dependencies like class-variance-authority and clsx declared in package.json48-53

Library Type Checking

The skipLibCheck: true setting tsconfig.json10 skips type checking of .d.ts files in node_modules/. This:

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

The library declares peer dependencies for React 18/19 in package.json55-58 relying on consumer projects to provide compatible versions. Sources: tsconfig.json9-12 package.json30 package.json48-53 package.json55-58 package.json62

Integration with Build Scripts

The TypeScript configuration integrates with several build scripts defined in package.json. Build Script Integration Diagram

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

The npm run build command package.json22 executes:

tsc -p tsconfig.json

This:

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

The output is consumed by the NPM package distribution documented in Package Structure.

Type Check Script

The npm run type-check command package.json23 executes:

tsc --noEmit

The --noEmit flag:

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

This script verifies type safety without the overhead of emitting JavaScript.

Lint Script Integration

The npm run lint command package.json24 runs ESLint on TypeScript files:

eslint src --ext .ts,.tsx

ESLint respects the TypeScript configuration through:

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

The npm run lint:fix variant package.json25 automatically fixes fixable issues. Sources: package.json22-25 tsconfig.json1-26

Summary

The TypeScript configuration in @ui8kit/core establishes a modern, type-safe build pipeline:

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

This configuration supports the three-layer architecture documented in Architecture while enabling multiple distribution methods described in Package Structure. Sources: tsconfig.json1-26 package.json22-25 package.json30-43

Getting started

Architecture

Components

Development Guide

TypeScript Configuration

TypeScript Configuration

Configuration Overview

Compilation Target Settings

Target: ES2022

Module System: ES2022

Module Resolution: Bundler

Type System Configuration

Strict Mode

Declaration Generation

Composite Projects

Path Alias Configuration

Base URL

Path Mappings

Internal Imports: `@/*`

Package Entry Point: `@ui8kit/core`

Build Output Configuration

Root Directory

Output Directory

Declaration Directory

Include and Exclude Patterns

Include Pattern

Exclude Pattern

Special Compiler Options

Bun Runtime Types

JSON Module Resolution

CommonJS Interoperability

Library Type Checking

Integration with Build Scripts

Build Script

Type Check Script

Lint Script Integration

Summary

​TypeScript Configuration

​Configuration Overview

​Compilation Target Settings

​Target: ES2022

​Module System: ES2022

​Module Resolution: Bundler

​Type System Configuration

​Strict Mode

​Declaration Generation

​Composite Projects

​Path Alias Configuration

​Base URL

​Path Mappings

​Internal Imports: @/*

​Package Entry Point: @ui8kit/core

​Build Output Configuration

​Root Directory

​Output Directory

​Declaration Directory

​Include and Exclude Patterns

​Include Pattern

​Exclude Pattern

​Special Compiler Options

​Bun Runtime Types

​JSON Module Resolution

​CommonJS Interoperability

​Library Type Checking

​Integration with Build Scripts

​Build Script

​Type Check Script

​Lint Script Integration

​Summary

TypeScript Configuration

Configuration Overview

Compilation Target Settings

Target: ES2022

Module System: ES2022

Module Resolution: Bundler

Type System Configuration

Strict Mode

Declaration Generation

Composite Projects

Path Alias Configuration

Base URL

Path Mappings

Internal Imports: `@/*`

Package Entry Point: `@ui8kit/core`

Build Output Configuration

Root Directory

Output Directory

Declaration Directory

Include and Exclude Patterns

Include Pattern

Exclude Pattern

Special Compiler Options

Bun Runtime Types

JSON Module Resolution

CommonJS Interoperability

Library Type Checking

Integration with Build Scripts

Build Script

Type Check Script

Lint Script Integration

Summary