Object UI

The Universal Schema-Driven UI Engine

From JSON to world-class UI in minutes

Documentation | Quick Start | Migration Guide

🎉 What's New in v0.4.0

Component Namespaces

Organize components into namespaces to prevent naming conflicts:

ComponentRegistry.register('button', ButtonComponent, {
  namespace: 'ui'  // ✨ New: Prevent conflicts across plugins
});

Lazy Field Registration

Load only the fields you need for 30-50% smaller bundles:

import { registerField } from '@object-ui/fields';

// Only load what you use
registerField('text');
registerField('number');
// 70% smaller bundle size! 🚀

Build Performance

3-5x faster CI builds with Turbo v2
Parallel package builds with intelligent caching
Instant rebuilds for unchanged packages

👉 Read the Migration Guide for details and examples.

🚀 Quick Start (Development Mode)

Since this package is not yet published to NPM, here is how to play with the source code:

Clone & Install

git clone https://github.com/objectstack-ai/objectui.git
cd objectui
pnpm install
# Build the core engine
pnpm build

Run the ObjectStack Console

Start the unified development console to preview your apps and objects:
```
pnpm dev
# Opens http://localhost:5173
```
Try the Minimal Console Example (New!)

See how to integrate ObjectUI in your own app:
```
cd examples/minimal-console
pnpm dev
# Opens http://localhost:5174
```
Edit & Reload

Edit the JSON schema files and the changes will be instantly reflected in the browser.

Examples

ObjectStack examples that demonstrate different features and use cases:

examples/crm - Full-featured CRM application with dashboards, multiple views (Grid, Kanban, Map, Gantt), and custom server implementation.
examples/todo - Simple task management app demonstrating basic ObjectStack configuration and field types.
examples/kitchen-sink - Comprehensive component catalog showing all available field types, dashboard widgets, and view types.
examples/msw-todo - Frontend-first development example using MSW (Mock Service Worker) to run ObjectStack in the browser.
examples/minimal-console ⭐ NEW! - Minimal custom console in ~100 lines showing third-party integration without full console infrastructure. Uses @object-ui/app-shell and @object-ui/providers with custom routing and mock API.

Running Examples as API Servers

All examples (except msw-todo) can be run as API servers using @objectstack/cli:

# From the monorepo root
pnpm run serve:crm          # Start CRM example on http://localhost:3000
pnpm run serve:todo         # Start Todo example on http://localhost:3000
pnpm run serve:kitchen-sink # Start Kitchen Sink example on http://localhost:3000

# Or from individual example directories
cd examples/crm
pnpm run serve

Each server provides:

GraphQL API endpoint: http://localhost:3000/graphql
REST API endpoints based on object definitions
Sample data loaded from the configuration manifest

📦 For React Developers

Option 1: Full Console (ObjectStack Backend)

Install the core packages to use <SchemaRenderer> inside your Next.js or Vite app with ObjectStack backend:

npm install @object-ui/react @object-ui/components @object-ui/data-objectstack

Option 2: Minimal Integration (Any Backend) ⭐ NEW!

Use ObjectUI components without the full console infrastructure. Perfect for integrating into existing apps:

npm install @object-ui/app-shell @object-ui/providers

Then build your own console in ~100 lines:

import { AppShell, ObjectRenderer } from '@object-ui/app-shell';
import { ThemeProvider, DataSourceProvider } from '@object-ui/providers';

function MyConsole() {
  return (
    <ThemeProvider>
      <DataSourceProvider dataSource={myAPI}>
        <AppShell sidebar={<MySidebar />}>
          <ObjectRenderer objectName="contact" />
        </AppShell>
      </DataSourceProvider>
    </ThemeProvider>
  );
}

Benefits:

🎯 Lightweight: ~50KB vs 500KB+ full console
🔌 Any Backend: REST, GraphQL, custom APIs (not just ObjectStack)
🎨 Full Control: Custom routing, auth, layouts
📦 Cherry-pick: Use only what you need

See examples/minimal-console for a complete working example.

🎨 Beautiful by Default

Professional designs using Tailwind CSS and Shadcn/UI
Light/dark theme support
Fully customizable with utility classes
WCAG 2.1 AA accessible

⚡ Blazing Fast

3x faster page loads than traditional low-code platforms
6x smaller bundle sizes (< 50KB vs 300KB+)
Built on React 18+ with automatic optimizations
Tree-shakable architecture

🚀 Developer Friendly

TypeScript-first with complete type definitions
Zero learning curve if you know React
Works with existing tools and workflows
Full control - extend or customize anything

🛠️ Production Ready

85%+ test coverage
Enterprise security built-in
Comprehensive documentation
Active development and support

🔥 Phase 3: Enterprise Data Protocol (NEW!)

Advanced Field Types: Vector (AI embeddings), Grid (sub-tables), Formula, Summary
Query AST Builder: SQL-like queries with joins, aggregations, subqueries
Smart Validation: 30+ rules, async validation, cross-field dependencies
Multi-Datasource: Health monitoring, connection pooling, query caching
40+ Filter Operators: Date ranges, lookup filters, full-text search
Object Inheritance: Triggers, advanced permissions, metadata caching

Why Object UI?

For You as a Developer

Stop Writing Repetitive UI Code

// Traditional React: 200+ lines
function UserForm() {
  // ... useState, validation, handlers, JSX
}

// Object UI: 20 lines
const schema = {
  type: "crud",
  api: "/api/users",
  columns: [...]
}

Better Performance, Smaller Bundle

Automatic code splitting
Lazy-loaded components
Zero runtime CSS overhead
Optimized for production

Full Control & Flexibility

Mix with existing React code
Override any component
Custom themes with Tailwind
Export to standard React anytime

vs Other Solutions

Feature	Object UI	Amis	Formily	Material-UI
Tailwind Native	✅	❌	❌	❌
Bundle Size	50KB	300KB+	200KB+	500KB+
TypeScript	✅ Full	Partial	✅ Full	✅ Full
Tree Shakable	✅	❌	⚠️ Partial	⚠️ Partial
Server Components	✅	❌	❌	⚠️ Coming
Visual Designer	✅	✅	❌	❌

Quick Start

Option 1: Using CLI (Fastest Way) 🚀

The easiest way to get started is using the Object UI CLI:

# Install the CLI globally
npm install -g @object-ui/cli

# Create a new app from JSON schema
objectui init my-app

# Start the development server
cd my-app
objectui serve app.schema.json

Your app will be running at http://localhost:3000! 🎉

Just edit app.schema.json to build your UI - no React code needed.

Option 2: Using as a Library

Installation

# Using npm
npm install @object-ui/react @object-ui/components

# Using yarn
yarn add @object-ui/react @object-ui/components

# Using pnpm
pnpm add @object-ui/react @object-ui/components

Basic Usage

import React from 'react'
import { SchemaRenderer } from '@object-ui/react'
import { registerDefaultRenderers } from '@object-ui/components'

// Register default components once
registerDefaultRenderers()

const schema = {
  type: "page",
  title: "Dashboard",
  body: {
    type: "grid",
    columns: 3,
    items: [
      { type: "card", title: "Total Users", value: "${stats.users}" },
      { type: "card", title: "Revenue", value: "${stats.revenue}" },
      { type: "card", title: "Orders", value: "${stats.orders}" }
    ]
  }
}

function App() {
  const data = {
    stats: { users: 1234, revenue: "$56,789", orders: 432 }
  }
  
  return <SchemaRenderer schema={schema} data={data} />
}

export default App

Copy-Paste Schema Examples

📝 Contact Form

{
  "type": "form",
  "title": "Contact Us",
  "fields": [
    { "name": "name", "type": "text", "label": "Full Name", "required": true },
    { "name": "email", "type": "email", "label": "Email", "required": true },
    { "name": "subject", "type": "select", "label": "Subject", "options": [
      { "label": "General Inquiry", "value": "general" },
      { "label": "Bug Report", "value": "bug" },
      { "label": "Feature Request", "value": "feature" }
    ]},
    { "name": "message", "type": "textarea", "label": "Message", "required": true }
  ],
  "actions": [{ "type": "submit", "label": "Send Message" }]
}

📊 Data Grid

{
  "type": "crud",
  "api": "/api/users",
  "columns": [
    { "name": "name", "label": "Name", "sortable": true },
    { "name": "email", "label": "Email" },
    { "name": "role", "label": "Role", "type": "select", "options": ["Admin", "User", "Viewer"] },
    { "name": "status", "label": "Status", "type": "badge" },
    { "name": "created_at", "label": "Joined", "type": "date" }
  ],
  "filters": [
    { "name": "role", "type": "select", "label": "Filter by Role" },
    { "name": "status", "type": "select", "label": "Filter by Status" }
  ],
  "showSearch": true,
  "showCreate": true,
  "showExport": true
}

📈 Dashboard

{
  "type": "dashboard",
  "title": "Sales Dashboard",
  "widgets": [
    { "type": "stat-card", "title": "Revenue", "value": "${stats.revenue}", "trend": "+12%", "w": 3, "h": 1 },
    { "type": "stat-card", "title": "Orders", "value": "${stats.orders}", "trend": "+8%", "w": 3, "h": 1 },
    { "type": "stat-card", "title": "Customers", "value": "${stats.customers}", "trend": "+5%", "w": 3, "h": 1 },
    { "type": "stat-card", "title": "Conversion", "value": "${stats.conversion}", "trend": "-2%", "w": 3, "h": 1 },
    { "type": "chart", "chartType": "line", "title": "Revenue Over Time", "w": 8, "h": 3 },
    { "type": "chart", "chartType": "pie", "title": "Sales by Region", "w": 4, "h": 3 }
  ]
}

🔄 Kanban Board

{
  "type": "kanban",
  "objectName": "tasks",
  "groupBy": "status",
  "titleField": "title",
  "cardFields": ["assignee", "priority", "due_date"],
  "columns": [
    { "value": "todo", "label": "To Do", "color": "#6366f1" },
    { "value": "in_progress", "label": "In Progress", "color": "#f59e0b" },
    { "value": "review", "label": "In Review", "color": "#3b82f6" },
    { "value": "done", "label": "Done", "color": "#22c55e" }
  ]
}

📖 More examples: See examples/ for complete working applications.

📦 Packages

Object UI is a modular monorepo with packages designed for specific use cases:

Core Packages

Package	Description	Size
@object-ui/types	TypeScript definitions and protocol specs	10KB
@object-ui/core	Core logic, validation, registry, expression evaluation	20KB
@object-ui/react	React bindings and `SchemaRenderer`	15KB
@object-ui/components	Standard UI components (Tailwind + Shadcn)	50KB
@object-ui/fields	Field renderers and registry	12KB
@object-ui/layout	Layout components with React Router integration	18KB

CLI & Tools

Package	Description	Size
@object-ui/cli	CLI tool for building apps from JSON schemas	25KB
@object-ui/runner	Universal application runner for testing schemas	30KB
vscode-extension	VSCode extension with IntelliSense and live preview	32KB

Data Adapters

Package	Description	Size
@object-ui/data-objectstack	ObjectStack data adapter	8KB

Plugins (Lazy-Loaded)

Plugin	Description	Size
@object-ui/plugin-aggrid	AG Grid data grid integration	150KB
@object-ui/plugin-calendar	Calendar and event management	25KB
@object-ui/plugin-charts	Chart components powered by Recharts	80KB
@object-ui/plugin-chatbot	Chatbot interface components	35KB
@object-ui/plugin-dashboard	Dashboard layouts and widgets	22KB
@object-ui/plugin-editor	Rich text editor powered by Monaco	120KB
@object-ui/plugin-form	Advanced form components	28KB
@object-ui/plugin-gantt	Gantt chart visualization	40KB
@object-ui/plugin-grid	Advanced data grid	45KB
@object-ui/plugin-kanban	Kanban boards with drag-and-drop	100KB
@object-ui/plugin-map	Map visualization	60KB
@object-ui/plugin-markdown	Markdown rendering	30KB
@object-ui/plugin-timeline	Timeline components	20KB
@object-ui/plugin-view	ObjectQL-integrated views (grid, form, detail)	35KB

🔌 Data Integration

Object UI is designed to work with any backend through its universal DataSource interface:

ObjectStack Integration

npm install @object-ui/core

import { createObjectStackAdapter } from '@object-ui/core';

const dataSource = createObjectStackAdapter({
  baseUrl: 'https://api.example.com',
  token: 'your-auth-token'
});

// Use with any component
<SchemaRenderer schema={schema} dataSource={dataSource} />

Custom Data Sources

You can create adapters for any backend (REST, GraphQL, Firebase, etc.) by implementing the DataSource interface:

import type { DataSource, QueryParams, QueryResult } from '@object-ui/types';

class MyCustomDataSource implements DataSource {
  async find(resource: string, params?: QueryParams): Promise<QueryResult> {
    // Your implementation
  }
  // ... other methods
}

Data Source Examples →

🎯 What Can You Build?

Object UI is perfect for:

✅ Admin Panels - Complete CRUD interfaces in minutes
✅ Dashboards - Data visualization and analytics
✅ Forms - Complex multi-step forms with validation
✅ CMS - Content management systems
✅ Internal Tools - Business applications
✅ Prototypes - Rapid UI prototyping

🛣️ Roadmap

Phase 1-2 (Q4 2025 - Q1 2026) ✅ COMPLETED:

✅ Core schema rendering engine
✅ 40+ production-ready components (Shadcn + Tailwind)
✅ Expression system with field references
✅ Action system (AJAX, chaining, conditions)
✅ Theme system (light/dark mode)
✅ Report builder with exports
✅ Visual designer (beta)

Phase 3 (Q1-Q2 2026) ✅ COMPLETED:

✅ Advanced Field Types: Vector (AI embeddings), Grid (sub-tables), Formula, Summary
✅ ObjectSchema Enhancements: Inheritance, triggers, advanced permissions, metadata caching
✅ QuerySchema AST: SQL-like query building with joins, aggregations, subqueries
✅ Advanced Filtering: 40+ operators, date ranges, lookup filters, full-text search
✅ Validation Engine: 30+ rules, async validation, cross-field validation
✅ DriverInterface: Transactions, batch operations, connection pooling, query caching
✅ DatasourceSchema: Multi-datasource management, health monitoring

Phase 4+ (Q2-Q4 2026):

🔄 Real-time collaboration features
🔄 Mobile-optimized components
🔄 AI-powered schema generation
🔄 Advanced workflow automation

See PHASE3_IMPLEMENTATION.md for detailed Phase 3 documentation.

🤝 Contributing

We welcome contributions! Please read our Contributing Guide for details.

For Developers

📖 Contributing Guide - How to contribute to the project
🏗️ Architecture Evaluation - Comprehensive architecture analysis and improvement recommendations (中文版)
🔄 ObjectStack Spec Alignment - Alignment analysis with ObjectStack Spec v0.7.1 and development roadmap (中文版)
🔌 Console Plugin Evaluation - Transform console into a reusable plugin for HotCRM integration

Development Setup

Quick Setup (Recommended):

# Clone the repository
git clone https://github.com/objectstack-ai/objectui.git
cd objectui

# Run automated setup script
./scripts/setup.sh

Manual Setup:

# Clone the repository
git clone https://github.com/objectstack-ai/objectui.git
cd objectui

# Install dependencies
pnpm install

# Build all packages
pnpm build

# Run the development site
pnpm dev

# Run tests
pnpm test

📄 License

Object UI is MIT licensed.

🌟 Community & Support

⭐ Star on GitHub - Show your support!
📖 Documentation - Comprehensive guides and API reference
🐛 Report Issues - Found a bug? Let us know
📧 Email Us - Get in touch

🙏 Acknowledgments

Object UI is inspired by and builds upon ideas from:

Amis - Schema-driven UI framework
Formily - Form solution
Shadcn/UI - UI component library
Tailwind CSS - Utility-first CSS framework

Built with ❤️ by the ObjectQL Team

Website · Documentation · GitHub

FilesExpand file tree

README.md

Latest commit

History