Umi max enterprise

Umi Max — Enterprise Patterns

Umi Max (@umijs/max) is a curated bundle of plugins on top of UmiJS: convention-based routing, a hooks-based global data store ("Model"), a unified request layer, role-based access control, and a ProLayout-based shell — all wired together so an enterprise admin app needs almost no boilerplate. The defaults are opinionated. The biggest mistake an agent can make here is reaching for generic React patterns (Redux, raw fetch, hand-rolled route guards, custom admin shells, plain antd Table) when Umi Max and ProComponents already have a convention-based answer.

Before writing code in an Umi Max project, identify which system the task touches, and read the matching reference file:

Task involves...	Read
Global state, shared data between components, useModel, @@initialState	references/data-flow.md
Calling a REST backend, useRequest, error handling, interceptors, request config	references/request.md
Permissions, roles, "can this user see/do X", route guards, <Access>	references/access.md
Page shell, sidebar menu, route config, page title/icon, hiding nav items	references/layout-routing.md
Data tables, search forms, CRUD list pages, column actions, toolbar	references/pro-table.md
ProForm, ModalForm, DrawerForm, StepsForm, ProCard, ProDescriptions, ProList, ProSkeleton	references/pro-components.md
antd Form, Upload, Modal, Drawer, Notification, ConfigProvider, Statistic	references/antd-components.md
Dynamic server-driven menus, multi-tenant roles, fine-grained permissions	references/rbac.md
GraphQL queries, mutations, subscriptions, Apollo/urql setup	references/graphql.md
Dashboard charts, Line, Bar, Pie, DualAxes, Gauge, Tiny sparklines, org charts	references/charts.md

If a task touches more than one (e.g. "add a dashboard page with charts that only managers can see"), read all relevant files — they're short and meant to be combined.

Mental model

Umi Max + ProComponents + antd replace almost everything you'd normally hand-roll:

• Redux / Zustand / Context → Model (src/models/*.ts) + useModel()
• axios/fetch wrapper → built-in request / useRequest from @umijs/max
• Manual <PrivateRoute> guards → route access: key + src/access.ts
• Hand-built admin shell → layout plugin renders ProLayout from route config
• Custom table + search form → ProTable from @ant-design/pro-components
• antd Form boilerplate → ProForm, ModalForm, DrawerForm, StepsForm
• antd Card layouts → ProCard with split, colSpan, tabs
• Record detail views → ProDescriptions
• Chart.js / Recharts → @ant-design/charts (Line, Column, Pie, Gauge, etc.)
• Custom GraphQL wiring → Apollo Client or urql via rootContainer in src/app.tsx

Project conventions an agent must respect

1. Use the max CLI, not umi. Scaffolding commands are npx max g ....
2. Respect directory conventions:
   • Models: src/models/*.ts or co-located src/pages/xxx/models/
   • Services (API calls): src/services/*.ts
   • Access rules: src/access.ts (single file, default export)
   • Route config: config/config.ts or config/routes.ts — check which exists
   • Runtime config (interceptors, layout, GraphQL provider): src/app.ts / src/app.tsx
   • GraphQL: src/graphql/client.ts, src/graphql/queries/, src/graphql/generated/
3. Import from @umijs/max, not from react-redux, axios, react-router-dom for things Umi Max provides.
4. Import ProComponents from @ant-design/pro-components, not from antd.
5. Import charts from @ant-design/charts, not from recharts, chart.js, or echarts.
6. TypeScript types: RequestConfig and RunTimeLayoutConfig are exported from @umijs/max.
7. Backend is the source of truth for permissions. Client-side RBAC is UX polish only.
8. Wrap the app in <App> from antd and use App.useApp() for message/modal/notification — never call them as static module imports.
9. Do not override antd styles with .ant-* CSS selectors — use ConfigProvider design tokens.

Quick examples

Model + useModel:

// src/models/userModel.ts
import { useState, useCallback } from 'react';
import { getUser } from '@/services/user';
export default function useUserModel() {
  const [user, setUser] = useState<any>(null);
  const fetchUser = useCallback(async () => setUser(await getUser()), []);
  return { user, fetchUser };
}
// In a component:
const { user } = useModel('userModel');

REST request:

const { data, loading } = useRequest(() => getUserList({ page: 1 }));

Access:

// src/access.ts
export default function access(initialState: any) {
  const perms = new Set<string>(initialState?.currentUser?.permissions ?? []);
  return { canAdmin: initialState?.currentUser?.role === 'admin', canWriteUsers: perms.has('user:write') };
}
// Route:
{ path: '/admin', component: 'Admin', access: 'canAdmin' }

ProTable:

<ProTable rowKey="id" request={async (params) => {
  const res = await getUserList(params);
  return { data: res.data, success: true, total: res.total };
}} columns={columns} />

ModalForm:

<ModalForm title="Create User" trigger={<Button type="primary">+ New</Button>}
  modalProps={{ destroyOnClose: true }}
  onFinish={async (values) => { await createUser(values); return true; }}>
  <ProFormText name="name" label="Name" rules={[{ required: true }]} />
</ModalForm>

Dashboard chart:

import { Line } from '@ant-design/charts';
<div style={{ height: 280 }}>
  <Line data={data} xField="month" yField="revenue" smooth />
</div>

GraphQL provider (src/app.tsx):

import { ApolloProvider } from '@apollo/client';
import { apolloClient } from './graphql/client';
export function rootContainer(container: React.ReactNode) {
  return <ApolloProvider client={apolloClient}>{container}</ApolloProvider>;
}

RBAC dynamic menu:

export const layout: RunTimeLayoutConfig = ({ initialState }) => ({
  menu: { request: async () => fetchMenuByRole(initialState?.currentUser?.role) },
});

Read the relevant reference file before writing real code — each one covers configuration options, gotchas, and patterns that are not safe to guess.