This document provides an introduction to Windbase, covering its purpose, features, architecture, and target users. For detailed information about the package structure and dependencies, see Package Architecture. For in-depth architectural details, see Architecture.
Windbase is an open-source visual builder for TailwindCSS that enables designers and developers to create, preview, and export Tailwind-based UI components without writing code manually. The application provides a drag-and-drop interface, live preview capabilities, and bidirectional transformation between HTML/JSX and an internal element representation.
The system provides two primary access methods:
| Interface | Command/URL | Implementation |
|---|---|---|
| CLI | npx windbase | Launches local development server running the Next.js application |
| Web | editor.windbase.dev | Hosted instance deployed on Netlify |
Both interfaces provide the same visual builder functionality, backed by the apps/web Next.js application that consumes the @windbase/engine state management layer and @windbase/ui component library.
The system is built as a TypeScript monorepo using pnpm workspaces, with Nx orchestrating builds and Vite powering the development experience.
Sources: README.md44-56 apps/web packages/engine/package.json1-29
Windbase serves three primary functions:
| Function | Description |
|---|---|
| Visual Design | Provides a drag-and-drop interface for constructing TailwindCSS layouts without manual coding |
| Import/Export | Supports bidirectional transformation between HTML/JSX source code and visual representation |
| Configuration Management | Enables custom TailwindCSS configuration editing with live preview integration |
The system maintains an internal element hierarchy represented by the BuilderElement and EditorElement types, which can be transformed to/from DOM structures and exported to production-ready HTML.
Sources: README.md21-22 README.md36-42
localStorage serializationSources: README.md36-42
The following diagram shows the package dependency graph and their primary responsibilities:
This architecture follows a strict layered dependency model:
apps/web consumes all packages@windbase/engine with useBuilder hook and six Zustand slices@windbase/coreSources: packages/core/package.json1-17 packages/utils/package.json1-20 packages/exporters/package.json1-21 packages/engine/package.json1-29 packages/ui/package.json1-42
| Package | Purpose | Key Exports | Dependencies |
|---|---|---|---|
@windbase/core | Foundation type definitions | EditorElement, CoreElement, coreToEditor(), editorToCore() | None (zero dependencies) |
@windbase/utils | DOM transformation utilities | domElementToBuilderElement(), findElementById(), removeElementById() | @windbase/core |
@windbase/exporters | HTML generation | exportToFullHtml(), exportToHtml(), renderElement() | @windbase/core, @windbase/utils |
@windbase/engine | Zustand state management | useBuilder(), BuilderStore, six state slices | @windbase/core, @windbase/utils, @windbase/exporters, zustand@5.0.6 |
@windbase/ui | UI component library | Button, Dialog, Tooltip, Tabs, Separator | @radix-ui/react-*, tailwindcss@4.1.11 |
apps/web | Next.js application | VisualBuilder, LivePreview, ElementLayers, ElementProperties | All @windbase/* packages |
The dependency flow ensures @windbase/core remains the foundation with no internal dependencies, allowing all other packages to build upon its type definitions. The @windbase/engine package orchestrates the system by integrating core types, utilities, and exporters into a cohesive state management layer accessed via the useBuilder() hook.
Sources: packages/core/package.json1-17 packages/engine/package.json14-28 packages/ui/package.json16-41
Windbase uses three primary element representations:
Type Definitions and Transformation Functions:
| Type | Package | Purpose | Key Properties |
|---|---|---|---|
EditorElement | @windbase/core | Runtime editing format in BuilderStore | id, tag, classes[], attributes, content, children[], parent, isContentEditable |
CoreElement | @windbase/core | Portable serialization format | Same as EditorElement but without parent and isContentEditable |
| DOM Element | Browser native | Input from HTML import | Native browser element properties |
| HTML String | Export format | Output from exportToFullHtml() | Complete HTML document with embedded Tailwind config |
Transformation Functions:
domElementToBuilderElement() - Converts DOM to EditorElement (@windbase/utils)editorToCore() - Strips editor metadata for serialization (@windbase/core)coreToEditor() - Reconstructs EditorElement from CoreElement (@windbase/core)exportToFullHtml() - Generates complete HTML document from CoreElement (@windbase/exporters)renderElement() - Generates HTML fragment from element tree (@windbase/exporters)Sources: packages/core/package.json1-17 packages/utils/package.json1-20 packages/exporters/package.json1-21
Windbase serves three primary user groups:
Sources: README.md10-11 README.md21-22
The following diagram maps high-level system names to their concrete technical implementations:
| Layer | Technology | Version | Configuration File | Purpose |
|---|---|---|---|---|
| Framework | React + Next.js | 18.x / Latest | apps/web | Server and client components |
| Type System | TypeScript | 5.8 | tsconfig.base.json | Strict type checking with module: "nodenext" |
| Package Manager | pnpm | Latest | pnpm-workspace.yaml | Workspace protocol with hoisting |
| Monorepo | Nx | Latest | nx.json | Build orchestration with @nx/js, @nx/react, @nx/vite |
| State | Zustand | 5.0.6 | packages/engine | BuilderStore with six slices |
| Styling | TailwindCSS | 4.1.11 | packages/ui | @tailwindcss/vite plugin integration |
| UI Primitives | Radix UI | Various | packages/ui/package.json | @radix-ui/react-dialog, react-dropdown-menu, etc. |
| Code Quality | Biome | Latest | biome.json | Format (quoteStyle: 'single') + Lint + Import organize |
| Testing | Vitest | Latest | packages/engine | Unit tests with JSDOM |
Sources: packages/engine/package.json23-28 packages/ui/package.json16-41 tsconfig.base.json1-21 biome.json1-35 pnpm-workspace.yaml1-3
The project uses a pnpm workspace with packages organized under two directories defined in pnpm-workspace.yaml1-3:
Package Organization:
packages/* - Five core libraries: @windbase/core, @windbase/utils, @windbase/exporters, @windbase/engine, @windbase/uiapps/* - Applications: apps/web (Next.js), apps/web-vite (Vite)Key Configuration Files:
| File | Purpose | Key Settings |
|---|---|---|
pnpm-workspace.yaml | Workspace definition | Packages in packages/* and apps/* |
.npmrc | pnpm configuration | strict-peer-dependencies=false, auto-install-peers=true |
tsconfig.base.json | Base TypeScript config | strict: true, module: "nodenext", target: "es2022" |
biome.json | Code quality config | quoteStyle: 'single', trailingCommas: 'none', organize imports |
.vscode/settings.json | Editor settings | defaultFormatter: "biomejs.biome", format on save |
Sources: pnpm-workspace.yaml1-3 tsconfig.base.json1-21 .npmrc1-3 biome.json1-35 .vscode/settings.json1-9
The base TypeScript configuration in tsconfig.base.json1-21 enforces strict type checking and project references for incremental builds:
| Option | Value | Purpose |
|---|---|---|
composite | true | Enable TypeScript project references |
strict | true | Enable all strict type checking options |
noUnusedLocals | true | Report unused local variables |
noImplicitReturns | true | Require explicit return statements |
noFallthroughCasesInSwitch | true | Require break statements in switch cases |
skipLibCheck | true | Skip type checking of .d.ts files |
target | es2022 | Compile to ES2022 JavaScript |
module | nodenext | Use Node.js ESM module resolution |
isolatedModules | true | Ensure files can be transpiled independently |
customConditions | ["development"] | Enable development-mode package.json exports |
The composite: true setting enables TypeScript project references, allowing packages to depend on each other's type information for faster incremental compilation.
Sources: tsconfig.base.json2-20
Option 1: Run Locally
Option 2: Visit Hosted Editor Visit editor.windbase.dev
For detailed setup instructions including development environment configuration, see Development Setup.
Sources: README.md44-56
The high-level architecture consists of four primary layers:
Layer Descriptions:
npx windbase) and web (editor.windbase.dev)apps/web) - Next.js application with React components: VisualBuilder, LivePreview, ElementLayers, ElementProperties, Toolbar@windbase/engine) - Zustand-based BuilderStore accessed via useBuilder() hook with six slices:
HistorySlice - Undo/redo with saveToHistory() debouncingSelectionSlice - Element selection via selectElement() and hoverElement()ManipulationSlice - CRUD operations: addElement(), updateElement(), deleteElement(), moveElement()TemplateSlice - Template loading and HTML export via exportHtml()PagesSlice - Multi-page management with pages: Map<string, Page>GlobalConfigSlice - TailwindCSS configuration storage@windbase/core - Type definitions (EditorElement, CoreElement) and transformations@windbase/utils - DOM conversion (domElementToBuilderElement()) and element utilities@windbase/exporters - HTML generation (exportToFullHtml(), renderElement())@windbase/ui - Radix-based component libraryFor detailed architectural information including state management patterns, element manipulation, and export pipeline, see Architecture.
Sources: packages/engine/package.json1-29 README.md21-22 README.md44-56
Windbase is in active early development. The project is working toward a v1.0 release with breaking changes expected between versions.
Development Status:
Track v1.0 progress at the project milestone: https://github.com/windbase/windbase/milestone/1
Sources: README.md16-17 README.md58-62 packages/core/package.json3 CHANGELOG.md1-89
Refresh this wiki