TypeScript Configuration

Relevant source files

The following files were used as context for generating this wiki page:

• tsconfig.json
• package.json
• cubic.yaml
• src/provider/index.tsx
• src/theme/colors.ts
• src/index.ts

The TypeScript configuration for the @pcstyle/ui project defines the compilation boundaries, type-safety rules, and module resolution strategies required to build a React-based component library. It ensures that the source code, written in TypeScript and TSX, is correctly transformed into modern JavaScript (ESM) while maintaining strict type integrity across the design system.

The configuration emphasizes a modern development workflow by targeting ES2020 and using the ESNext module system. This setup supports advanced features such as dual-theme state management and visual effects while providing the necessary declaration files for downstream consumers of the library.

Sources: tsconfig.json:1-20, package.json:1-15

Compiler Options and Environment

The core compiler settings are optimized for a library environment that integrates with modern bundlers and React 18+ environments.

Target and Module Resolution

The project targets ES2020 to utilize modern JavaScript features while ensuring compatibility with standard environments. Module resolution is set to bundler, which is specifically designed for modern tools that resolve modules similarly to how web browsers or specialized bundlers (like Vite or Webpack) operate.

Sources: tsconfig.json:3-6

Compilation Table

The following table summarizes the primary compiler options defined in the project:

Option	Value	Description
target	ES2020	Specifies the ECMAScript target version for emitted JavaScript.
module	ESNext	Sets the module system for the program.
jsx	react-jsx	Enables the modern React JSX transform that doesn't require importing React.
declaration	true	Generates corresponding .d.ts files for the library.
declarationMap	true	Generates a sourcemap for every corresponding .d.ts file.
rootDir	./src	Specifies the root folder within source files.
outDir	./dist	Redirects output structure to the directory.
strict	true	Enables all strict type-checking options.

Sources: tsconfig.json:2-15

Strict Type Safety Standards

The project enforces high sensitivity for type safety through both TypeScript's internal checks and external CI/CD rules defined in the repository configuration.

Internal Strictness

By setting strict: true in tsconfig.json, the project enables:

• noImplicitAny
• strictNullChecks
• strictFunctionTypes
• strictBindCallApply
• strictPropertyInitialization
• noImplicitThis
• alwaysStrict

Sources: tsconfig.json:12

External Custom Rules

The cubic.yaml configuration complements the TypeScript compiler by enforcing "STRICT_TYPES". This rule prohibits the use of the any type and non-null assertions to ensure deep type safety and explicit return types for public APIs.

Sources: cubic.yaml:22-24

The diagram shows the build flow where source files must pass both standard strict checks and custom architectural rules before generating distribution files.
Sources: tsconfig.json:10-14, cubic.yaml:22-27, package.json:20

Project Structure and Exports

The TypeScript configuration works in tandem with package.json to define how the library's types are exposed to consumers.

Module Path Mapping

The project uses a structured export system to provide clean API access. The package.json file maps specific entry points to their generated type declarations.

Export Path	Type Declaration File	Implementation File
.	./dist/index.d.ts	./dist/index.js
./theme	./dist/theme/index.d.ts	./dist/theme/index.js
./effects	./dist/effects/index.d.ts	./dist/effects/index.js

Sources: package.json:7-19

Build and Development Scripts

Compilation is handled directly via the TypeScript compiler (tsc).

• Build: tsc executes a one-time compilation of the /src directory into /dist.
• Dev: tsc --watch monitors file changes for incremental compilation.
• Lint: eslint is used to augment type checking by linting .ts and .tsx files in the src directory.

Sources: package.json:23-27

Type Integration in Components

The TypeScript configuration supports complex React patterns, including Context-based state management and dynamic theme switching.

The sequence diagram illustrates how the UIContextType interface and ThemeMode type union ensure type safety during theme transitions.
Sources: src/provider/index.tsx:6-12, src/theme/colors.ts:37

The library utilizes a ThemeMode type, defined as a union of "cyber" | "minimal", which is enforced across all UI components via the useUI hook. This prevents invalid theme strings from being passed into the provider or used in component logic.

Sources: src/theme/colors.ts:37, src/provider/index.tsx:15-18

Conclusion

The TypeScript configuration of @pcstyle/ui is designed for strictness and modern output. By combining tsconfig.json settings with project-specific rules in cubic.yaml, the system ensures that components are highly predictable and that the exported library provides high-quality type definitions for developers. This configuration serves as the foundation for the project's dual-theme architecture and its reactive UI components.