React Component Writing Guide

Styling

Component Priority

1. src/components — project-specific reusable components
2. @lobehub/ui/base-ui — headless primitives (Select, Modal, DropdownMenu, Popover, Switch, ScrollArea…)
3. @lobehub/ui — higher-level components (ActionIcon, Markdown, DragPage…)
4. Custom implementation — last resort; never reach for antd directly

If unsure about available components, search existing code or check node_modules/@lobehub/ui/es/index.mjs.

Common @lobehub/ui Components

Layout

Use Flexbox and Center from @lobehub/ui. See references/layout-kit.md for full props and examples.

• Use gap instead of margin for spacing between flex children
• Use flex={1} to fill available space
• Nest Flexbox for complex layouts; set overflow: 'auto' for scrollable regions

Navigation

For SPA pages, use react-router-dom, NOT next/link.

// ❌ Wrong
import Link from 'next/link';

// ✅ Correct
import { Link, useNavigate } from 'react-router-dom';

Access navigate from stores: useGlobalStore.getState().navigate?.('/settings');

Desktop File Sync Rule

Files with a .desktop.ts(x) variant must be edited in sync. Drift causes blank pages in Electron.

After editing any .ts/.tsx: glob for <filename>.desktop.{ts,tsx} in the same directory. If found, apply the equivalent sync-import change.

Routing Architecture

Router utilities:

import { dynamicElement, redirectElement, ErrorBoundary } from '@/utils/router';
element: dynamicElement(() => import('./chat'), 'Desktop > Chat');
element: redirectElement('/settings/profile');
errorElement: <ErrorBoundary />;

Common Mistakes