How frappe/frappe-ui works
Project Type and Purpose
• Frappe UI is an open-source Vue 3 component library + utility toolkit built on TailwindCSS.
• It’s designed to be consumed by other Vue applications (e.g., Frappe Cloud, Gameplan) and provides:
– A plugin layer to auto-register components
– A catalog of reusable UI components
– Utility modules (data-fetching composables, directives, helper functions)
– A TailwindCSS preset for theming
– Rich-text editor extensions (TipTap)
High-Level File Structure Analysis
• Top-level:
– src/ – source code (components, composables, directives, utilities, data-fetching, tailwind config)
– vite/ – build and code-generation scripts for types and dev server proxy
– docs/ – Markdown + Storybook stories for documentation site
– .github/workflows/ – CI for tests, builds, publishing to NPM
– package.json & tsconfig/vite.config – build, test, lint configuration
• Key layers inside src/:
a. components/ – individual Vue component folders, each with .vue, index.ts, types
b. data-fetching/ – composables for REST calls, real-time, local store
c. directives/ – Vue directives (e.g., onOutsideClick)
d. utils/ – helper functions (date handling, socket, upload, markdown, tailwind config)
README Insights
• Under-the-Hood tech stack: Vue 3 plugin, TailwindCSS, Headless UI, TipTap, dayjs
• Usage pattern: consumer imports FrappeUI plugin → app.use(FrappeUI) → Tailwind preset in consumer tailwind.config.js
• Continuous enrichment via vite scripts (type generation, proxy) and docs driven by Histoire/Storybook
Components
A. Core Plugin Layer
– FrappeUI (Vue plugin entrypoint) registers all components, directives, provides theme and utilities.
B. Component Modules
– UI Components (Button, Dialog, DatePicker, etc.)
C. Utility Layer
– Data-fetching composables (useCall, useDoc, useList, useNewDoc)
– Directives (onOutsideClick, visibility)
– Shared utils (debounce, markdown, socketio, dayjs wrappers)
D. Tailwind Preset Layer
E. Build & Distribution
– Vite build scripts (bundle to ESM/CJS, type generation)
– Vitest for unit tests
– GitHub Actions for CI/CD and NPM publish
F. Documentation Site
– docs/ driven by Histoire/Storybook, sources from components/**/*.story.*
Relationships and Data Flows
• “FrappeUI Plugin” → “Component Modules” for auto-registration
• “Component Modules” → “Utility Layer” for composables/directives
• “Components” → “Tailwind Preset” for styling
• “Build & Distribution” processes “src/” and “vite/” → publishes to NPM
• “Documentation Site” reads from “src/” + “docs/” via Histoire pipeline
Architectural Patterns & Design Principles
• Modular design: each component lives in its own folder with isolated types
• Plugin pattern: single entrypoint auto-wires all modules
• Composable API: data-fetching layers expose reactive hooks
• Utility-first CSS: Tailwind preset integrated with component classes
• Code generation: Vite scripts generate types and proxies for Frappe REST APIs
Technologies and Frameworks to Annotate
• Vue 3 Plugin System, Composition API
• TailwindCSS + Headless UI
• TipTap (ProseMirror) for rich-text
• Vite (build), Vitest (testing), Histoire/Storybook (docs)
• GitHub Actions (CI/CD), NPM registry