# heroui-inc/tailwind-variants architecture

> Architecture diagram of the GitHub repository heroui-inc/tailwind-variants, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/heroui-inc/tailwind-variants
- Repository: https://github.com/heroui-inc/tailwind-variants

## Overview

##### Project type and purpose
- This is an open-source **JavaScript/TypeScript utility library** named **tailwind-variants**.
- Purpose: Provide a first-class API for generating and composing Tailwind CSS class variants in a fully typed, framework-agnostic way.

##### File structure
- Top-level config files: .eslintrc.json, .prettierrc.json, tsconfig.json, jest.config.js, benchmark.js, CI workflows under .github/workflows.
- Source code under **src/**:
- index.js / index.d.ts – library entry point exporting `tv` API
- utils.js / utils.d.ts – internal helper functions (class merging, deep defaults)
- config.d.ts – type definitions for variant configuration
- setupTests.ts – test setup for Jest
- Tests under **src/__tests__/** validating `createTV`, the main `tv` function, and utilities.
- Build & packaging: package.json scripts, clean-package.config.json, copy-types.cjs for shipping .d.ts files, pnpm-lock.yaml.

##### README for additional insights
- Features highlight a **Variants Engine** with support for: base styles, variants, compoundVariants, defaultVariants, slots, composition, conflict resolution.
- Framework-agnostic: can be consumed by React, Vue, or plain HTML.
- Tailwindcss v4 support, automatic conflict resolution.

##### Main components & interactions
a. Components
- **API Layer (tv function)** – public interface where users define their variant config.
- **Variants Engine** – core algorithm that:
– Validates & merges variant inputs
– Resolves base, variant, compoundVariants, defaultVariants
– Outputs final class string
- **Utils Module** – low-level helpers for deep merging, conflict resolution, class concatenation.
- **Test Suite (Jest)** – tests driving the expected behavior and regression checks.
- **Build & Publish Pipeline** – Rollup/TS compiler (implicitly from package.json scripts), copy-types, benchmark script, CI workflows.
- **External Dependencies** – Tailwind CSS (as a styling engine), NPM registry (for distribution).

b. Relationships & data flow
1. **User Code** calls → `tv(config)`
2. `tv` invokes → **Variants Engine**
3. Variants Engine uses → **Utils Module** + **Type Definitions**
4. Engine returns → CSS class string → back to User Code
5. **Tests** import `tv` and **Utils Module** to validate outputs
6. On commit/PR, **CI Pipeline** runs ESLint, Prettier, Jest, benchmark.js
7. Build scripts generate dist code + copy-type definitions → published on NPM

c. Architectural patterns & principles
- **Functional, side-effect-free core**: all merges & resolutions return new strings/objects.
- **Modular separation**: clear split between API, engine logic, utilities, types.
- **Test-driven development**: comprehensive test suite for behavior correctness.
- **CI/CD integration**: automated linting, testing, and publishing workflows.

d. Key technologies & frameworks
- JavaScript / TypeScript
- Jest (testing)
- ESLint / Prettier (code quality)
- Husky & lint-staged (pre-commit hooks)
- GitHub Actions (CI workflows)
- NPM / pnpm (package management)

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% External Actors
  UC["User Code"]:::external
  TC["Tailwind CSS"]:::external
  NPM["NPM Registry"]:::external

  %% Library Modules
  subgraph "Library Modules"
    API["tv() API Layer"]:::api
    Engine["Variants Engine"]:::core
    Utils["Utils Module"]:::core
    Types["Type Definitions"]:::core
  end

  %% Test Suite
  subgraph "Test Suite"
    Setup["Test Setup"]:::infra
    Tests["Jest Tests"]:::infra
  end

  %% CI/CD & Build Pipeline
  subgraph "CI/CD & Build Pipeline"
    Lint["ESLint & Prettier"]:::infra
    TestProc["Run Jest Tests"]:::infra
    Build["Build & Package"]:::infra
    Publish["Publish to NPM"]:::infra
    Benchmark["Benchmark Script"]:::infra
    CopyTypes["Copy Types"]:::infra
    CleanConfig["Clean Package Config"]:::infra
    CIWorkflow["CI Workflow"]:::infra
    TSConfig["Project tsconfig.json"]:::infra
  end

  %% Flows: User Integration
  UC -->|"call tv(config)"| API
  API -->|"invoke engine"| Engine
  Engine -->|"use helpers"| Utils
  Engine -->|"validate config"| Types
  Engine -->|"returns class string"| UC
  Engine -.->|"leverages rules"| TC

  %% Test flows
  Setup --> Tests
  Tests -->|"import tv() & utils"| API
  Tests --> Utils

  %% Pipeline flows
  CIWorkflow --> Lint
  CIWorkflow --> TestProc
  CIWorkflow --> Benchmark
  CIWorkflow --> Build
  Build --> CopyTypes
  Build --> CleanConfig
  Build --> Publish
  Publish --> NPM

  TSConfig --> API
  TSConfig --> Engine
  TSConfig --> Utils
  TSConfig --> Types

  %% Click events
  click API "https://github.com/heroui-inc/tailwind-variants/blob/main/src/index.js"
  click API "https://github.com/heroui-inc/tailwind-variants/blob/main/src/index.d.ts"
  click Engine "https://github.com/heroui-inc/tailwind-variants/blob/main/src/index.js"
  click Utils "https://github.com/heroui-inc/tailwind-variants/blob/main/src/utils.js"
  click Utils "https://github.com/heroui-inc/tailwind-variants/blob/main/src/utils.d.ts"
  click Types "https://github.com/heroui-inc/tailwind-variants/blob/main/src/config.d.ts"
  click Tests "https://github.com/heroui-inc/tailwind-variants/tree/main/src/__tests__/"
  click Setup "https://github.com/heroui-inc/tailwind-variants/blob/main/src/setupTests.ts"
  click CIWorkflow "https://github.com/heroui-inc/tailwind-variants/blob/main/.github/workflows/ci.yml"
  click Benchmark "https://github.com/heroui-inc/tailwind-variants/blob/main/benchmark.js"
  click CopyTypes "https://github.com/heroui-inc/tailwind-variants/blob/main/copy-types.cjs"
  click CleanConfig "https://github.com/heroui-inc/tailwind-variants/blob/main/clean-package.config.json"
  click TSConfig "https://github.com/heroui-inc/tailwind-variants/blob/main/tsconfig.json"

  %% Styling
  classDef api fill:#cfe2ff,stroke:#2a7ae2,color:#0654ba
  classDef core fill:#d1e7dd,stroke:#0f5132,color:#0b2e13
  classDef infra fill:#e2e3e5,stroke:#6c757d,color:#202124
  classDef external fill:#fff3cd,stroke:#ff8800,color:#997404
```
