# macaron-css/macaron architecture

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

- Interactive diagram: https://gitdiagram.com/macaron-css/macaron
- Repository: https://github.com/macaron-css/macaron

## Overview

##### Project Type and Purpose
- Project Type: A TypeScript‑based monorepo (managed with npm workspaces) that publishes a suite of inter‑related packages.
- Purpose: Provide a zero‑runtime, type‑safe, colocated CSS‑in‑JS solution with first‑class support for React, Solid, and Qwik, plus integrations for Babel, esbuild, and Vite.

##### File Structure
Top‑level directories and their roles:
- packages/ – core libraries & integrations
– core: fundamental style‑extraction logic
– babel, esbuild, vite: compile‑time plugins that hook into each tool
– integration: shared glue code for invoking transforms
– react, solid, qwik: framework adapters exposing styled/ style APIs
- examples/ – small demo apps showing how to consume each adapter
- site/ – documentation website built with React/Solid components & Vite
- scripts/ – build, config, publish orchestration scripts
- .github/workflows/deploy.yml – CI/CD pipeline that runs build/tests/publish

##### README for Additional Insights
- Core features: zero‑runtime via build‑time CSS extraction; variants API
- Supported runtimes & integrations: React, Solid, Qwik, esbuild, Vite, Babel
- The “How it works” link describes the extraction pipeline and AST transforms

##### Main Components & Their Relationships
A. Developer Source Code
– TSX/JSX files importing from @macaron‑css/react|solid|qwik
B. Compile‑Time Tooling
1. Babel Plugin (packages/babel)
2. esbuild Plugin (packages/esbuild)
3. Vite Plugin (packages/vite)
4. Shared Integration Layer (packages/integration)
C. Core Extraction Engine (packages/core)
– AST parsing, style evaluation, class‑name generation, CSS extraction
D. Framework Adapters (packages/react, packages/solid, packages/qwik)
– expose styled(), css(), runtime helpers (zero runtime or minimal)
E. Output Artifacts
– Transformed JS/TS modules with injected class names
– Generated CSS bundle or per‑file CSS assets
F. Consumers
– Example apps (examples/)
– Documentation site (site/)
– End users’ front‑end applications
G. CI/CD & Publishing
– GitHub Actions workflow → run tests (jest.config.js) → build scripts → npm publish via scripts/publish.ts

1. Developer code → passes through chosen plugin (B)
2. Plugin invokes core engine (C) via integration layer (B.4)
3. Core extracts CSS, emits class‑name mapping + CSS files
4. Framework adapter code (D) uses those mappings at runtime (zero‑cost)
5. Final artifacts are served or bundled by user’s bundler (Vite/esbuild/Rollup/etc.)

##### Architectural Patterns & Design Principles
- Monorepo with npm workspaces for cross‑package sharing
- Plugin‑based architecture: each build tool has its own thin plugin layer
- Core‑logic isolation: all AST parsing and style‑extraction lives in packages/core
- Adapter pattern: framework‑specific packages wrap core APIs for each UI library
- Zero‑runtime principle: extract everything at build time, no CSS‑in‑JS runtime

##### Diagramming Recommendations
– code → plugin → core → CSS + augmented code → runtime
– Blue: Core extraction engine
– Green: Plugins (Babel/esbuild/Vite)
– Orange: Framework adapters (React/Solid/Qwik)
– Gray: Consumers (examples/site/user apps)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Developer Source Code
    subgraph "Developer Source Code" 
        direction TB
        DevReact["React Example\nexamples/react/src"]:::dev
        DevSolidStart["Solid Start Example\nexamples/solid-start/src"]:::dev
        DevSolid["Solid Example\nexamples/solid/src"]:::dev
        DevVanilla["Vanilla Example\nexamples/vanilla/src"]:::dev
        DevVite["Vite Example\nexamples/vite/src"]:::dev
    end

    %% Compile-Time Tooling Plugins
    subgraph "Compile-Time Tooling" 
        direction TB
        BabelPlugin["Babel Plugin\npackages/babel"]:::plugins
        EsbuildPlugin["esbuild Plugin\npackages/esbuild"]:::plugins
        VitePlugin["Vite Plugin\npackages/vite"]:::plugins
        IntegrationLayer["Integration Layer\npackages/integration"]:::plugins
    end

    %% Core Extraction Engine
    Core["Core Extraction Engine\npackages/core"]:::core

    %% Framework Adapters
    subgraph "Framework Adapters"
        direction TB
        ReactAdapter["React Adapter\npackages/react"]:::adapters
        SolidAdapter["Solid Adapter\npackages/solid"]:::adapters
        QwikAdapter["Qwik Adapter\npackages/qwik"]:::adapters
    end

    %% Output Artifacts
    Artifacts["Output Artifacts\nTransformed Modules + CSS"]:::core

    %% Consumers
    subgraph "Consumers"
        direction TB
        Examples["Example Apps\nexamples/"]:::consumers
        DocSite["Docs Site\nsite/"]:::consumers
        UserApps["User Frontend Apps"]:::consumers
    end

    %% CI/CD & Publishing
    CI["CI/CD & Publishing\n.github/workflows/deploy.yml\nscripts/build.ts\nscripts/publish.ts"]:::ci

    %% Connections
    DevReact -->|uses plugin| BabelPlugin
    DevSolidStart -->|uses plugin| EsbuildPlugin
    DevSolid -->|uses plugin| VitePlugin
    DevVanilla -->|uses plugin| EsbuildPlugin
    DevVite -->|uses plugin| VitePlugin

    BabelPlugin -->|invokes| IntegrationLayer
    EsbuildPlugin -->|invokes| IntegrationLayer
    VitePlugin -->|invokes| IntegrationLayer

    IntegrationLayer -->|calls core APIs| Core
    Core -->|generates CSS + mappings| Artifacts

    Artifacts -->|used by| ReactAdapter
    Artifacts -->|used by| SolidAdapter
    Artifacts -->|used by| QwikAdapter

    ReactAdapter -->|bundled into| Examples
    SolidAdapter -->|bundled into| Examples
    QwikAdapter -->|bundled into| Examples

    Examples -->|demo| UserApps
    DocSite -->|renders using adapters| UserApps

    CI -->|tests & publishes| Core
    CI -->|tests & publishes| BabelPlugin
    CI -->|tests & publishes| EsbuildPlugin
    CI -->|tests & publishes| VitePlugin
    CI -->|tests & publishes| ReactAdapter
    CI -->|tests & publishes| SolidAdapter
    CI -->|tests & publishes| QwikAdapter

    %% Click Events
    click DevReact "https://github.com/macaron-css/macaron/tree/main/examples/react/src"
    click DevSolidStart "https://github.com/macaron-css/macaron/tree/main/examples/solid-start/src"
    click DevSolid "https://github.com/macaron-css/macaron/tree/main/examples/solid/src"
    click DevVanilla "https://github.com/macaron-css/macaron/tree/main/examples/vanilla/src"
    click DevVite "https://github.com/macaron-css/macaron/tree/main/examples/vite/src"

    click BabelPlugin "https://github.com/macaron-css/macaron/tree/main/packages/babel"
    click EsbuildPlugin "https://github.com/macaron-css/macaron/tree/main/packages/esbuild"
    click VitePlugin "https://github.com/macaron-css/macaron/tree/main/packages/vite"
    click IntegrationLayer "https://github.com/macaron-css/macaron/tree/main/packages/integration"

    click Core "https://github.com/macaron-css/macaron/tree/main/packages/core"
    click ReactAdapter "https://github.com/macaron-css/macaron/tree/main/packages/react"
    click SolidAdapter "https://github.com/macaron-css/macaron/tree/main/packages/solid"
    click QwikAdapter "https://github.com/macaron-css/macaron/tree/main/packages/qwik"

    click Examples "https://github.com/macaron-css/macaron/tree/main/examples/"
    click DocSite "https://github.com/macaron-css/macaron/tree/main/site/"

    click CI "https://github.com/macaron-css/macaron/blob/main/.github/workflows/deploy.yml"

    %% Styles
    classDef dev fill:#E0FFFF,stroke:#000
    classDef plugins fill:#90EE90,stroke:#000
    classDef core fill:#ADD8E6,stroke:#000
    classDef adapters fill:#FFA500,stroke:#000
    classDef consumers fill:#D3D3D3,stroke:#000
    classDef ci fill:#F0E68C,stroke:#000
```
