# anber/wyw-in-js architecture

> Architecture diagram of the GitHub repository anber/wyw-in-js, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-02-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/anber/wyw-in-js
- Repository: https://github.com/anber/wyw-in-js

## Overview

##### Project Type and Purpose
- From the README, note that WyW-in-JS is a toolkit that enables developers to create their own zero-runtime CSS-in-JS libraries. It provides an API for custom processors, handles arbitrary JS during build-time, and includes integration tools for popular bundlers such as Webpack, Vite, esbuild, etc.
- The monorepo structure (as seen in the file tree) indicates various sub-projects such as website, crates (Rust modules for advanced processing), and numerous npm packages (for CLI, bundler plugins, transformation pipelines, etc.). This supports the idea that the toolkit is made to be flexible and extensible.

##### File Structure to Identify Major Components
- Monorepo Root: Contains configuration files (pnpm-workspace.yaml, turbo.json, tsconfig files, etc.) to coordinate a large set of packages.
- Apps: The “apps/website” folder – likely a Next.js-based demo/documentation site that showcases the library and its usage.
- Crates: The “crates” directory holds Rust-based packages (e.g., wyw_macros, wyw_processor, wyw_traverse). These are likely used for compile-time code generation, macro processing, or for enhancing performance in transformation tasks.
- Packages: The “packages” directory contains a variety of Node.js packages divided by functionality:
o Integration modules such as babel-preset, cli, esbuild, rollup, webpack-loader – these provide integration with build tools and transformation workflows.
o Shared utilities and processor helpers (processor-utils, shared, transform) that form the core transformation logic.
- Examples and E2E test directories: They validate processor behavior and provide hands-on usage examples (object-syntax, template-tag-syntax, etc.).
- Configurations: The “configs” folder holds configuration settings for babel, jest, eslint, and TypeScript.

##### Key Components and Architectural Elements
a. Core Processing Engine:
- The core transformation work is performed across packages:
– Rust Crates: “crates/wyw_macros”, “crates/wyw_processor”, and “crates/wyw_traverse” implement low-level processing or macro expansions.
– JS Transformation Pipeline: “packages/transform” contains logic for parsing, collecting exports/imports, and transformation workflow.
- Utility libraries: “packages/processor-utils” and “packages/shared” provide commonly used functions and types needed across transformations.
b. Integration & Tooling:
- CLI Tools: “packages/cli” offer a command-line interface allowing developers to trigger the build or transformation processes.
- Bundler Plugins/Loaders: “packages/webpack-loader”, “packages/vite”, “packages/rollup”, and “packages/esbuild” expose integrations for bundlers. They wrap around the core transformation engine to integrate during bundling.
- Presets: “packages/babel-preset” (and related configs) allow the usage of the toolkit in Babel-powered environments.
c. End-user Interface / Documentation:
- “apps/website” is the frontend application that showcases documentation, guides, and examples of how to use the toolkit.
d. Testing and Examples:
- “e2e”, “examples”, and the “__tests__” directories within many packages ensure the robustness of each module and demonstrate usage patterns.
e. Build and Configuration:
- The root contains a number of configuration files (.github workflows, turbo, pnpm, tsconfig, etc.) that define the build, testing, and deployment processes.

##### Relationships and Data Flow
- User Code / Custom Style Definitions ‒→ CLI/Build Tools (using packages/cli, bundler plugins)
- CLI and Build Integrations route the source files through the Transformation Pipeline (packages/transform and processor-utils)
- The Transformation Pipeline may invoke Rust-based macros/processors (crates/wyw_processor, wyw_macros) to create the final artifacts.
- The output of the processors is then integrated back into application code by bundler plugins (webpack-loader, vite, rollup).
- Documentation, examples, and tests ensure these components interact as expected.

##### Architectural Patterns & Design Principles
- Modularity: Each package or crate is responsible for a narrowly defined set of functionalities (for example, transformation, bundler integration, CLI).
- Separation of Concerns: There is a clean division between the core transformation engine, the integration layers, and the public API.
- Extensibility: API hooks are provided (via processors and custom plugins) to allow developers to implement arbitrary syntax or handle custom packaging logic.
- Polyglot Environment: Combining Rust-based performance-critical modules with Node.js tooling to achieve efficient build-time processing.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global Configuration and Workspace
    CONFIG["Build & Configuration"]:::config
    click CONFIG "https://github.com/anber/wyw-in-js/tree/main/configs"
    
    %% External: User Code
    USER["User Code/Custom Styles"]:::external

    %% Integration & Tooling Layer
    subgraph "Integration & Tooling"
        CLI["CLI Tools"]:::node
        click CLI "https://github.com/anber/wyw-in-js/tree/main/packages/cli"
        subgraph "Bundler Plugins"
            WP["Webpack Loader"]:::node
            click WP "https://github.com/anber/wyw-in-js/tree/main/packages/webpack-loader"
            VITE["Vite"]:::node
            click VITE "https://github.com/anber/wyw-in-js/tree/main/packages/vite"
            ROLLUP["Rollup"]:::node
            click ROLLUP "https://github.com/anber/wyw-in-js/tree/main/packages/rollup"
            ESBUILD["Esbuild"]:::node
            click ESBUILD "https://github.com/anber/wyw-in-js/tree/main/packages/esbuild"
            BABEL["Babel Preset"]:::node
            click BABEL "https://github.com/anber/wyw-in-js/tree/main/packages/babel-preset"
        end
    end

    %% JavaScript Transformation Pipeline
    TRANSFORM["JS Transformation Pipeline"]:::node
    click TRANSFORM "https://github.com/anber/wyw-in-js/tree/main/packages/transform"

    %% Core Processing Engine
    subgraph "Core Processing Engine"
        subgraph "Rust Crates"
            WYW_MACROS["wyw_macros"]:::rust
            click WYW_MACROS "https://github.com/anber/wyw-in-js/tree/main/crates/wyw_macros"
            WYW_PROCESSOR["wyw_processor"]:::rust
            click WYW_PROCESSOR "https://github.com/anber/wyw-in-js/tree/main/crates/wyw_processor"
            WYW_TRAVERSE["wyw_traverse"]:::rust
            click WYW_TRAVERSE "https://github.com/anber/wyw-in-js/tree/main/crates/wyw_traverse"
        end
        subgraph "Shared Utilities"
            PROC_UTILS["processor-utils"]:::node
            click PROC_UTILS "https://github.com/anber/wyw-in-js/tree/main/packages/processor-utils"
            SHARED["shared"]:::node
            click SHARED "https://github.com/anber/wyw-in-js/tree/main/packages/shared"
        end
    end

    %% End-user Interface / Documentation
    DOCS["Documentation Website"]:::frontend
    click DOCS "https://github.com/anber/wyw-in-js/tree/main/apps/website"

    %% Testing and Examples
    TEST["Testing and Examples"]:::testing
    click TEST "https://github.com/anber/wyw-in-js/tree/main/e2e"
    EXAMPLES["Examples"]:::testing
    click EXAMPLES "https://github.com/anber/wyw-in-js/tree/main/examples"

    %% Arrows / Data Flow
    USER -->|"triggers"| CLI
    USER -->|"initiates"| WP
    USER -->|"initiates"| VITE
    USER -->|"initiates"| ROLLUP
    USER -->|"initiates"| ESBUILD
    USER -->|"initiates"| BABEL

    CLI -->|"invokes"| TRANSFORM
    WP -->|"invokes"| TRANSFORM
    VITE -->|"invokes"| TRANSFORM
    ROLLUP -->|"invokes"| TRANSFORM
    ESBUILD -->|"invokes"| TRANSFORM
    BABEL -->|"invokes"| TRANSFORM

    TRANSFORM -->|"calls"| WYW_MACROS
    TRANSFORM -->|"calls"| WYW_PROCESSOR
    TRANSFORM -->|"calls"| WYW_TRAVERSE
    TRANSFORM -->|"uses"| PROC_UTILS
    TRANSFORM -->|"uses"| SHARED

    WYW_MACROS -->|"supports"| PROC_UTILS
    WYW_PROCESSOR -->|"supports"| SHARED

    WYW_PROCESSOR -.->|"outputs"| WP
    WYW_PROCESSOR -.->|"outputs"| VITE
    WYW_PROCESSOR -.->|"outputs"| ROLLUP
    WYW_PROCESSOR -.->|"outputs"| ESBUILD
    WYW_PROCESSOR -.->|"outputs"| BABEL

    %% Configuration connections
    CONFIG --- USER
    CONFIG --- CLI
    CONFIG --- TRANSFORM
    CONFIG --- WYW_MACROS
    CONFIG --- DOCS

    %% Documentation and Testing linkage
    DOCS --- TEST
    DOCS --- EXAMPLES

    %% Define Classes for Color Coding
    classDef rust fill:#ffaaaa,stroke:#cc0000,stroke-width:2px;
    classDef node fill:#aaffaa,stroke:#008800,stroke-width:2px;
    classDef frontend fill:#aaaaff,stroke:#0000cc,stroke-width:2px;
    classDef config fill:#ffffaa,stroke:#cccc00,stroke-width:2px;
    classDef testing fill:#ffaaff,stroke:#cc00cc,stroke-width:2px;
    classDef external fill:#d9d9d9,stroke:#333333,stroke-width:2px;
```
