Zango CRM React Framework

A dynamic CRM framework built with React that provides CRUD operations, profile views, and custom page capabilities out of the box.

Features

• 🚀 Dynamic Page Types: CRUD, Profile360, and Custom pages
• 📊 Advanced Data Tables: Server-side pagination, sorting, and filtering
• 📝 Dynamic Forms: JSON Schema-based form generation
• 🎨 API-driven Themes: Automatic theme application from API response
• 🔌 Plugin Architecture: Add custom pages without modifying core code
• 📱 Responsive Design: Works on desktop and mobile
• 🔄 Smart Navigation: Automatic routing between SPA and server routes

Installation

pnpm install @zango-core/crm-framework

Quick Start

import React from 'react';
import * as ZangoFramework from '@zango-core/crm-framework';
import * as customPages from './custom/pages';

const { ZangoApp } = ZangoFramework;

function App() {
  return <ZangoApp customPages={customPages} />;
}

export default App;

Environment Setup

Create .env file:

VITE_API_BASE_URL=http://localhost:8000
VITE_PROXY_ROUTES=/api,/zango,/frame

API Integration

Your backend should return this structure from /frame/router/initialize:

{
  "menu": [
    {
      "uri": "/app/doctors",
      "name": "Doctors", 
      "icon": "👨‍⚕️",
      "page_type": "crud",
      "entity": "doctors"
    }
  ],
  "routes": [
    {
      "path": "/app/doctors",
      "page_type": "crud", 
      "entity": "doctors"
    }
  ],
  "profile_info": {
    "name": "John Doe",
    "user_role": "Admin"
  },
  "theme": {
    "colors": {
      "primary": "#5048ed",
      "secondary": "#6d7280"
    }
  }
}

Creating Custom Pages

1. Create component in src/custom/pages/Dashboard.js:

import React from 'react';

const Dashboard = () => {
  return (
    <div style={{ padding: '24px' }}>
      <h1>Dashboard</h1>
      <p>Your custom content here</p>
    </div>
  );
};

export default Dashboard;

2. Export in src/custom/pages/index.js:

export { default as Dashboard } from './Dashboard';

3. Add to your API menu configuration:

{
  "uri": "/app/dashboard",
  "name": "Dashboard",
  "page_type": "custom",
  "component": "Dashboard"
}

Development Commands

# Development with hot reload
pnpm run dev

# Production build
pnpm run build

# Library build for npm publishing
pnpm run build:lib

# Zango platform build (creates single file for Zango platform)
pnpm run build:appbuilder

API Service Usage

The framework provides a modern API service:

import { 
  fetchAppInitData,
  fetchUserProfile,
  callApi 
} from '@zango-core/crm-framework';

// Direct convenience functions
const appData = await fetchAppInitData();
const profile = await fetchUserProfile();

// Custom API calls
const result = await callApi({
  url: '/custom/endpoint',
  type: 'GET'
});

if (result.success) {
  console.log(result.response);
}

Smart Navigation

Use SmartLink for automatic navigation handling:

import { SmartLink } from '@zango-core/crm-framework';

// Automatically uses React Router or browser navigation
<SmartLink to="/app/appointments">Appointments</SmartLink>
<SmartLink to="/external-page">External Page</SmartLink>

Architecture

• Framework (src/framework/): Core components and functionality
• Custom (src/custom/): Your customizations and pages
• API-driven: Routes, menu, and theme come from API
• Plugin-based: Add functionality without modifying core

Documentation

See COMPOSABLE-USAGE-EXAMPLES.md for detailed guides on:

• Page types (CRUD, Profile360, Custom)
• API integration patterns
• Theme customization
• Smart navigation system
• Development workflow
• Composable architecture patterns

License

MIT © Zango Team