ContextQMD
Back to Lobehub

React Component Writing Guide

.agents/skills/react/SKILL.md

2.2.17.8 KB
Original Source

React Component Writing Guide

Styling

ScenarioApproach
Most casescreateStaticStyles + cssVar.* (zero-runtime, module-level)
Simple one-offInline style attribute
Truly dynamic (JS color fns like readableColor/chroma)createStyles + token — last resort

Component Priority

  1. src/components — project-specific reusable components
  2. @lobehub/ui/base-ui — headless primitives. If the component lives here, use it. Do NOT import the same-named root export.
  3. @lobehub/ui — higher-level / antd-wrapping components (only when no base-ui equivalent)
  4. antd — only when neither base-ui nor @lobehub/ui root provides it
  5. Custom implementation — true last resort

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

@lobehub/ui/base-ui — always prefer for these

ComponentImport
Select (+ SelectProps, SelectOption)import { Select } from '@lobehub/ui/base-ui';
Modal (imperative API)import { createModal, confirmModal, useModalContext, type ModalInstance } from '@lobehub/ui/base-ui';
DropdownMenuimport { DropdownMenu } from '@lobehub/ui/base-ui';
ContextMenuimport { ContextMenu } from '@lobehub/ui/base-ui';
Popoverimport { Popover } from '@lobehub/ui/base-ui';
ScrollAreaimport { ScrollArea } from '@lobehub/ui/base-ui';
Switchimport { Switch } from '@lobehub/ui/base-ui';
Toastimport { Toast } from '@lobehub/ui/base-ui';
FloatingSheetimport { FloatingSheet } from '@lobehub/ui/base-ui';

For Modal specifically, see the dedicated modal skill — use the imperative createModal({ content: … }) pattern over the legacy <Modal open … /> declarative pattern. base-ui has its own ModalHost already mounted in SPAGlobalProvider.

Common slip: import { Select } from '@lobehub/ui' looks fine but it's the antd-backed Select. Use base-ui Select. Same for Modal, DropdownMenu, etc.

@lobehub/ui root — use when base-ui has no equivalent

CategoryComponents
GeneralActionIcon, ActionIconGroup, Block, Button, Icon
Data DisplayAvatar, Collapse, Empty, Highlighter, Markdown, Tag, Tooltip
Data EntryCodeEditor, CopyButton, EditableText, Form, Input, InputPassword, SearchBar, TextArea
FeedbackAlert, Drawer
LayoutCenter, DraggablePanel, Flexbox, Grid, Header, MaskShadow
NavigationBurger, Menu, SideNav, Tabs

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

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

tsx
// ❌ 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.

Base file (web)Desktop file (Electron)
desktopRouter.config.tsxdesktopRouter.config.desktop.tsx
componentMap.tscomponentMap.desktop.ts

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

Route TypeUse CaseImplementation
Next.js App RouterAuth pagessrc/app/[variants]/(auth)/
React Router DOMMain SPAdesktopRouter.config.tsx + .desktop.tsx (pair)

Router utilities:

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

Common Mistakes

MistakeFix
Using next/link in SPAUse react-router-dom Link
Using antd directlyUse @lobehub/ui/base-ui first, then @lobehub/ui
import { Select } from '@lobehub/ui'import { Select } from '@lobehub/ui/base-ui'
import { Modal } from '@lobehub/ui' + <Modal open> declarativecreateModal / confirmModal from @lobehub/ui/base-ui (see modal skill)
import { DropdownMenu/Popover/Switch } from '@lobehub/ui'Import same name from @lobehub/ui/base-ui instead
createStyles for static stylesUse createStaticStyles + cssVar
Editing only desktopRouter.config.tsxMust edit both .tsx and .desktop.tsx
Using margin for flex spacingUse gap prop on Flexbox
Accessing zustand store without selectorUse selectors to access store data (see zustand skill)
Text or icon-text actions built with Flexbox/Text + onClickUse Button type={'text'} size={'small'} with icon when needed