# formkit/formkit architecture

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

- Interactive diagram: https://gitdiagram.com/formkit/formkit
- Repository: https://github.com/formkit/formkit

## Overview

##### Overview of File Structure
- **Root**
- pnpm-workspace.yaml – workspace config
- scripts/ – build, bundle, lint, publish pipelines
- examples/ – standalone Vite/Vue demo app
- e2e/ – Playwright/Memory-DOM test suites
- .tests/ – shared Vitest helpers
- **packages/** – each subfolder is a self-contained npm package:
- core – reactive form engine, plugin registry, schema compiler
- inputs – built-in input scaffolding (checkbox, text, etc.)
- validation/rules – synchronous and async rules library
- i18n – locale files + formatters
- themes – CSS frameworks integrations (Genesis, Tailwind, Unocss)
- cli – Node.js binary for project scaffolding & exports
- vue – Vue 3 plugin, SSR bindings, composables
- nuxt – Nuxt module, SSR plugin
- tailwindcss – Tailwind plugin integration
- zod – Zod schema integration
- observer, utils, addons, dev – supplemental libs

##### Main Components & Their Roles
- **Core Engine** (packages/core)
- Node-based reactive form data model
- Schema compiler → renders Node tree
- Plugin registry for extensions
- **Plugin Packages**
- **Integrations**
- Vue plugin (packages/vue) injects components/composables for CSR & SSR
- Nuxt module (packages/nuxt) bootstraps SSR, auto-imports, hooks
- Tailwind plugin (packages/tailwindcss) theme utilities
- CLI (packages/cli) scaffolds projects, themes, exports components
- **Examples & Tests**
- examples/ – live demo harness
- e2e/ and .tests/ – proof-of-concept and regression tests
- **Build & CI/CD**
- scripts/ – compile TS, bundle ESM/CJS, publish to npm
- GitHub Actions – run Vitest, E2E, lint, build

##### Relationships & Data Flow
- Plugins depend on Core → register schema sections, inputs, rules
- Nuxt Module depends on Vue Plugin + SSR helper
- CLI depends on Core + Themes + Vue Plugin to scaffold new apps
- Examples app imports CLI-generated config or direct packages
- CI/CD triggers scripts → build each package → run tests → publish

##### Architectural Patterns & Principles
- **Monorepo & Workspace** – PNPM workspaces for atomic versions
- **Modular Plugin System** – core engine exposes plugin API for inputs, validation, theming
- **Schema-Driven Rendering** – JSON → AST → DOM via Vue components
- **Separation of Concerns** – core engine vs. UI layer vs. CLI vs. themes
- **SSR & CSR Support** – Vue plugin abstracts platform differences

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Workspace Root & CI/CD
    subgraph "Workspace Root"
        Root["pnpm-workspace.yaml"]:::tools
        Scripts["Build & CI/CD Scripts"]:::tools
        ExamplesApp["Examples App"]:::consumer
        E2E["End-to-End Tests"]:::consumer
        Vitest["Shared Vitest Helpers"]:::consumer
    end

    %% Engine Layer
    subgraph "Engine Layer"
        Core["Core Engine"]:::engine
    end

    %% Plugin Layer
    subgraph "Plugin Layer"
        Inputs["Inputs Plugin"]:::plugin
        Validation["Validation Rules"]:::plugin
        I18n["Internationalization (i18n)"]:::plugin
        Themes["Themes (CSS Integrations)"]:::plugin
        Icons["Icons Plugin"]:::plugin
        Zod["Zod Schema Integration"]:::plugin
        Observer["Observer Utility"]:::plugin
        Utils["Utility Functions"]:::plugin
        Addons["Addons"]:::plugin
        Dev["Dev Helpers"]:::plugin
    end

    %% Integration Layer
    subgraph "Integration Layer"
        Vue["Vue 3 Plugin"]:::integration
        Nuxt["Nuxt Module"]:::integration
        Tailwind["Tailwind CSS Plugin"]:::integration
        CLI["CLI Tool"]:::integration
    end

    %% Dependencies & Data Flow
    %% Plugins depend on Core
    Inputs -->|depends on| Core
    Validation -->|depends on| Core
    I18n -->|depends on| Core
    Themes -->|depends on| Core
    Icons -->|depends on| Core
    Zod -->|depends on| Core
    Observer -->|depends on| Core
    Utils -->|depends on| Core
    Addons -->|depends on| Core
    Dev -->|depends on| Core

    %% Core and Plugins feed Vue Plugin
    Core -->|extends| Vue
    Inputs -->|registers| Vue
    Validation -->|registers| Vue
    Themes -->|registers| Vue
    Icons -->|registers| Vue
    I18n -->|registers| Vue

    %% Vue Plugin to Nuxt Module
    Vue -->|bootstraps| Nuxt

    %% CLI scaffolding from Core, Themes, Vue
    Core -->|used by| CLI
    Themes -->|used by| CLI
    Vue -->|used by| CLI

    %% Scripts build & publish each package
    Scripts --> Core
    Scripts --> Inputs
    Scripts --> Validation
    Scripts --> I18n
    Scripts --> Themes
    Scripts --> Icons
    Scripts --> Zod
    Scripts --> Observer
    Scripts --> Utils
    Scripts --> Addons
    Scripts --> Dev
    Scripts --> Vue
    Scripts --> Nuxt
    Scripts --> Tailwind
    Scripts --> CLI

    %% Consumers import packages
    ExamplesApp -->|imports| Core
    ExamplesApp -->|imports| Vue
    E2E -->|tests| Core
    E2E -->|tests| Vue
    Vitest -->|helpers for| Core
    Vitest -->|helpers for| Vue

    %% Click Events
    click Core "https://github.com/formkit/formkit/tree/master/packages/core"
    click Inputs "https://github.com/formkit/formkit/tree/master/packages/inputs"
    click Validation "https://github.com/formkit/formkit/tree/master/packages/rules"
    click I18n "https://github.com/formkit/formkit/tree/master/packages/i18n"
    click Themes "https://github.com/formkit/formkit/tree/master/packages/themes"
    click Icons "https://github.com/formkit/formkit/tree/master/packages/icons"
    click Zod "https://github.com/formkit/formkit/tree/master/packages/zod"
    click Observer "https://github.com/formkit/formkit/tree/master/packages/observer"
    click Utils "https://github.com/formkit/formkit/tree/master/packages/utils"
    click Addons "https://github.com/formkit/formkit/tree/master/packages/addons"
    click Dev "https://github.com/formkit/formkit/tree/master/packages/dev"
    click Vue "https://github.com/formkit/formkit/tree/master/packages/vue"
    click Nuxt "https://github.com/formkit/formkit/tree/master/packages/nuxt"
    click Tailwind "https://github.com/formkit/formkit/tree/master/packages/tailwindcss"
    click CLI "https://github.com/formkit/formkit/tree/master/packages/cli"
    click ExamplesApp "https://github.com/formkit/formkit/tree/master/examples/"
    click E2E "https://github.com/formkit/formkit/tree/master/e2e/"
    click Vitest "https://github.com/formkit/formkit/tree/master/.tests/"

    %% Styles
    classDef engine fill:#D0E8FF,stroke:#0366d6,color:#0366d6
    classDef plugin fill:#E6FFDA,stroke:#22863A,color:#22863A
    classDef integration fill:#F0E6FF,stroke:#6F42C1,color:#6F42C1
    classDef tools fill:#F2F2F2,stroke:#444444,color:#444444
    classDef consumer fill:#FFF5B1,stroke:#D9A419,color:#D9A419
```
