component-refactoring

# Dify Component Refactoring Skill Refactor high-complexity React components in the Dify frontend codebase with the patterns and workflow below. > **Complexity Threshold**: Components with complexity > 50 (measured by `pnpm analyze-component`) should be refactored before testing. ## Quick Reference ### Commands (run from `web/`) Use paths relative to `web/` (e.g., `app/components/...`). Use `refactor-component` for refactoring prompts and `analyze-component` for testing prompts and metrics. ```bash cd web # Generate refactoring prompt pnpm refactor-component <path> # Output refactoring analysis as JSON pnpm refactor-component <path> --json # Generate testing prompt (after refactoring) pnpm analyze-component <path> # Output testing analysis as JSON pnpm analyze-component <path> --json ``` ### Complexity Analysis ```bash # Analyze component complexity pnpm analyze-component <path> --json # Key metrics to check: # - complexity: normalized score 0-100 (target < 50) # - maxComplexity: highest single function complexity # - lineCount: total lines (target < 300) ``` ### Complexity Score Interpretation | Score | Level | Action | |-------|-------|--------| | 0-25 | 🟢 Simple | Ready for testing | | 26-50 | 🟡 Medium | Consider minor refactoring | | 51-75 | 🟠 Complex | **Refactor before testing** | | 76-100 | 🔴 Very Complex | **Must refactor** | ## Core Refactoring Patterns ### Pattern 1: Extract Custom Hooks **When**: Component has complex state management, multiple `useState`/`useEffect`, or business logic mixed with UI. **Dify Convention**: Place hooks in a `hooks/` subdirectory or alongside the component as `use-<feature>.ts`. ```typescript // ❌ Before: Complex state logic in component const Configuration: FC = () => { const [modelConfig, setModelConfig] = useState<ModelConfig>(...) const [datasetConfigs, setDatasetConfigs] = useState<DatasetConfigs>(...) const [completionParams, setCompletionParams] = useState<FormValue>({}) // 50+ lines of state management logic... return <div>...</div> } // ✅ After: Extract to custom hook // hooks/use-model-config.ts export const useModelConfig = (appId: string) => { const [modelConfig, setModelConfig] = useState<ModelConfig>(...) const [completionParams, setCompletionParams] = useState<FormValue>({}) // Related state management logic here return { modelConfig, setModelConfig, completionParams, setCompletionParams } } // Component becomes cleaner const Configuration: FC = () => { const { modelConfig, setModelConfig } = useModelConfig(appId) return <div>...</div> } ``` **Dify Examples**: - `web/app/components/app/configuration/hooks/use-advanced-prompt-config.ts` - `web/app/components/app/configuration/debug/hooks.tsx` - `web/app/components/workflow/hooks/use-workflow.ts` ### Pattern 2: Extract Sub-Components **When**: Single component has multiple UI sections, conditional rendering blocks, or repeated patterns. **Dify Convention**: Place sub-components in subdirectories or as separate files in the same directory. ```typescript // ❌ Before: Monolithic JSX with multiple sections const AppInfo = () => { return ( <div> {/* 100 lines of header UI */} {/* 100 lines of operations UI */} {/* 100 lines of modals */} </div> ) } // ✅ After: Split into focused components // app-info/ // ├── index.tsx (orchestration only) // ├── app-header.tsx (header UI) // ├── app-operations.tsx (operations UI) // └── app-modals.tsx (modal management) const AppInfo = () => { const { showModal, setShowModal } = useAppInfoModals() return ( <div> <AppHeader appDetail={appDetail} /> <AppOperations onAction={handleAction} /> <AppModals show={showModal} onClose={() => setShowModal(null)} /> </div> ) } ``` **Dify Examples**: - `web/app/components/app/configuration/` directory structure - `web/app/components/workflow/nodes/` per-node organization ### Pattern 3: Simplify Conditional Logic **When**: Deep nesting (> 3 levels), complex ternaries, or multiple `if/else` chains. ```typescript // ❌ Before: Deeply nested conditionals const Template = useMemo(() => { if (appDetail?.mode === AppModeEnum.CHAT) { switch (locale) { case LanguagesSupported[1]: return <TemplateChatZh /> case LanguagesSupported[7]: return <TemplateChatJa /> default: return <TemplateChatEn /> } } if (appDetail?.mode === AppModeEnum.ADVANCED_CHAT) { // Another 15 lines... } // More conditions... }, [appDetail, locale]) // ✅ After: Use lookup tables + early returns const TEMPLATE_MAP = { [AppModeEnum.CHAT]: { [LanguagesSupported[1]]: TemplateChatZh, [LanguagesSupported[7]]: TemplateChatJa, default: TemplateChatEn, }, [AppModeEnum.ADVANCED_CHAT]: { [LanguagesSupported[1]]: TemplateAdvancedChatZh, // ... }, } const Template = useMemo(() => { const modeTemplates = TEMPLATE_MAP[appDetail?.mode] if (!modeTemplates) return null const TemplateComponent = modeTemplates[locale] || modeTemplates.default return <TemplateComponent appDetail={appDetail} /> }, [appDetail, locale]) ``` ### Pattern 4: Extract API/Data Logic **When**: Component directly handles API calls, data transformation, or complex async operations. **Dify Convention**: Use `@tanstack/react-query` hooks from `web/service/use-*.ts` or create custom data hooks. ```typescript // ❌ Before: API logic in component const MCPServiceCard = () => { const [basicAppConfig, setBasicAppConfig] = useState({}) useEffect(() => { if (isBasicApp && appId) { (async () => { const res = await fetchAppDetail({ url: '/apps', id: appId }) setBasicAppConfig(res?.model_config || {}) })() } }, [appId, isBasicApp]) // More API-related logic... } // ✅ After: Extract to data hook using React Query // use-app-config.ts import { useQuery } from '@tanstack/react-query' import { get } from '@/service/base' const NAME_SPACE = 'appConfig' export const useAppConfig = (appId: string, isBasicApp: boolean) => { return useQuery({ enabled: isBasicApp && !!appId, queryKey: [NAME_SPACE, 'detail', appId], queryFn: () => get<AppDetailResponse>(`/apps/${appId}`), select: data => data?.model_config || {}, }) } // Component becomes cleaner const MCPServiceCard = () => { const { data: config, isLoading } = useAppConfig(appId, isBasicApp) // UI only } ``` **React Query Best Practices in Dify**: - Define `NAME_SPACE` for query key organization - Use `enabled` option for conditional fetching - Use `select` for data transformation - Export invalidation hooks: `useInvalidXxx` **Dify Examples**: - `web/service/use-workflow.ts` - `web/service/use-common.ts` - `web/service/knowledge/use-dataset.ts` - `web/service/knowledge/use-document.ts` ### Pattern 5: Extract Modal/Dialog Management **When**: Component manages multiple modals with complex open/close states. **Dify Convention**: Modals should be extracted with their state management. ```typescript // ❌ Before: Multiple modal states in component const AppInfo = () => { const [showEditModal, setShowEditModal] = useState(false) const [showDuplicateModal, setShowDuplicateModal] = useState(false) const [showConfirmDelete, setShowConfirmDelete] = useState(false) const [showSwitchModal, setShowSwitchModal] = useState(false) const [showImportDSLModal, setShowImportDSLModal] = useState(false) // 5+ more modal states... } // ✅ After: Extract to modal management hook type ModalType = 'edit' | 'duplicate' | 'delete' | 'switch' | 'import' | null const useAppInfoModals = () => { const [activeModal, setActiveModal] = useState<ModalType>(null) const openModal = useCallback((type: ModalType) => setActiveModal(type), []) const closeModal = useCallback(() => setActiveModal(null), []) return { activeModal, openModal, closeModal, isOpen: (type: ModalType) => activeModal === type, } } ``` ### Pattern 6: Extract Form Logic **When**: Complex form validation, submission handling, or field transformation. **Dify Convention**: Use `@tanstack/react-form` patterns from `web/app/components/base/form/`. ```typescript // ✅ Use existing form infrastructure import { useAppForm } from '@/app/components/base/form' const ConfigForm = () => { const form = useAppForm({ defaultValues: { name: '', description: '' }, onSubmit: handleSubmit, }) return <form.Provider>...</form.Provider> } ``` ## Dify-Specific Refactoring Guidelines ### 1. Context Provider Extraction **When**: Component provides complex context values with multiple states. ```typescript // ❌ Before: Large context value object const value = { appId, isAPIKeySet, isTrailFinished, mode, modelModeType, promptMode, isAdvancedMode, isAgent, isOpenAI, isFunctionCall, // 50+ more properties... } return <ConfigContext.Provider value={value}>...</ConfigContext.Provider> // ✅ After: Split into domain-specific contexts <ModelConfigProvider value={modelConfigValue}> <DatasetConfigProvider value={datasetConfigValue}> <UIConfigProvider value={uiConfigValue}> {children} </UIConfigProvider> </DatasetConfigProvider> </ModelConfigProvider> ``` **Dify Reference**: `web/context/` directory structure ### 2. Workflow Node Components **When**: Refactoring workflow node components (`web/app/components/workflow/nodes/`). **Conventions**: - Keep node logic in `use-interactions.ts` - Extract panel UI to separate files - Use `_base` components for common patterns ``` nodes/<node-type>/ ├── index.tsx # Node registration ├── node.tsx # Node visual component ├── panel.tsx # Configuration panel ├── use-interactions.ts # Node-specific hooks └── types.ts # Type definitions ``` ### 3. Configuration Components **When**: Refactoring app configuration components. **Conventions**: - Separate config sections into subdirectories - Use existing patterns from `web/app/components/app/configuration/` - Keep feature toggles in dedicated components ### 4. Tool/Plugin Components **When**: Refactoring tool-related components (`web/app/components/tools/`). **Conventions**: - Follow existing modal patterns - Use service hooks from `web/service/use-tools.ts` - Keep provider-specific logic isolated ## Refactoring Workflow ### Step 1: Generate Refactoring Prompt ```bash pnpm refactor-component <path> ``` This command will: - Analyze component complexity and features - Identify specific refactoring actions needed - Generate a prompt for AI assistant (auto-copied to clipboard on macOS) - Provide detailed requirements based on detected patterns ### Step 2: Analyze Details ```bash pnpm analyze-component <path> --json ``` Identify: - Total complexity score - Max function complexity - Line count - Features detected (state, effects, API, etc.) ### Step 3: Plan Create a refactoring plan based on detected features: | Detected Feature | Refactoring Action | |------------------|-------------------| | `hasState: true` + `hasEffects: true` | Extract custom hook | | `hasAPI: true` | Extract data/service hook | | `hasEvents: true` (many) | Extract event handlers | | `lineCount > 300` | Split into sub-components | | `maxComplexity > 50` | Simplify conditional logic | ### Step 4: Execute Incrementally 1. **Extract one piece at a time** 2. **Run lint, type-check, and tests after each extraction** 3. **Verify functionality before next step** ``` For each extraction: ┌────────────────────────────────────────┐ │ 1. Extract code │ │ 2. Run: pnpm lint:fix │ │ 3. Run: pnpm type-check:tsgo │ │ 4. Run: pnpm test │ │ 5. Test functionality manually │ │ 6. PASS? → Next extraction │ │ FAIL? → Fix before continuing │ └────────────────────────────────────────┘ ```