MMnode/.claude/skills/comfyui-react-widget/SKILL.md
turtle89431 4ea8431cd0
Some checks are pending
Publish to Comfy registry / Publish Custom Node to registry (push) Waiting to run
init
2026-09-26 11:11:23 -07:00

459 lines
13 KiB
Markdown

---
name: comfyui-react-widget
description: Create React widgets in ComfyUI custom nodes. Covers createReactWidget wrapping, two-way data binding, render synchronization, extension registration, and component authoring conventions. Use when building new React widgets, debugging rendering issues, or registering custom widget types.
---
# ComfyUI React Widget
This project uses the `createReactWidget` factory function to mount React components as ComfyUI DOM widgets. This document describes how the entire mechanism works, key considerations, and complete examples.
---
## Architecture Overview
```
ComfyUI (LGraphNode)
└── addDOMWidget(name, type, container, options)
└── container (HTMLDivElement)
└── React Root (createRoot)
└── <YourWidget value={...} onChange={...} />
```
- **currentValue** — Always stored as a JSON string for ComfyUI serialization/deserialization
- **render()** — Called on every value change, passing the latest props to the React Root
- **getValue / setValue** — ComfyUI calls these hooks to sync node values
- **serializeValue** — Called when ComfyUI builds the API payload, returns currentValue
---
## Core Files
| File | Responsibility |
|------|----------------|
| `src/lib/create-react-widget.ts` | Widget factory, manages React Root, value storage, and ComfyUI two-way binding |
| `src/index.ts` | ComfyUI extension entry point, registers `getCustomWidgets` |
| `src/components/widgets/` | React widget components |
---
## Creating a New Widget: Complete Flow
### 1. Write the React Component
```tsx
// src/components/widgets/MyWidget.tsx
import type { ReactWidgetProps } from '@/lib/create-react-widget'
export interface MyData {
text: string
count: number
}
export function MyWidget({ value, onChange }: ReactWidgetProps<MyData>) {
// Key: derive data from value prop, don't use useState for main data
const data: MyData = value && typeof value === 'object'
? value as MyData
: { text: '', count: 0 }
function update(patch: Partial<MyData>) {
onChange({ ...data, ...patch })
}
return (
<div>
<Input value={data.text} onChange={e => update({ text: e.target.value })} />
</div>
)
}
```
### 2. Export the Component
```ts
// src/components/widgets/index.ts
export { MyWidget } from './MyWidget'
export type { MyData } from './MyWidget'
```
### 3. Register Widget Type in Entry Point
```ts
// src/index.ts
const [{ createReactWidget }, { MyWidget }] = await Promise.all([
import('@/lib/create-react-widget'),
import('@/components/widgets'),
])
globalThis.comfyAPI!.app.app.registerExtension({
name: 'EasyMedia.widgets',
async setup() {
addStylesheet(`/${import.meta.env.PROJECT_NAME}/globals.css`)
},
getCustomWidgets() {
return {
MY_WIDGET: createReactWidget<MyData>(MyWidget, {
defaultValue: JSON.stringify({ text: '', count: 0 }),
domWidgetOptions: {
getMinHeight: () => 80,
},
}),
}
},
})
```
### 4. Declare Corresponding Input Type in Python Node
```python
# nodes.py — Input type name must match getCustomWidgets key
@classmethod
def INPUT_TYPES(cls):
return {
"required": {
"my_data": ("MY_WIDGET", {}),
}
}
```
---
## createReactWidget Parameters
```ts
createReactWidget<T>(Component, options?)
```
| Parameter | Type | Description |
|-----------|------|-------------|
| `Component` | `React.ComponentType<ReactWidgetProps<T>>` | The React component to render |
| `options.defaultValue` | `string` | Initial JSON string, defaults to `''` |
| `options.height` | `number` | Fixed container height (px), auto-sized if not set |
| `options.domWidgetOptions` | `DOMWidgetOptions` | Passed through to `addDOMWidget`, can override `getMinHeight`, `getMaxHeight`, `hideOnZoom`, etc. |
### ReactWidgetProps\<T\>
```ts
interface ReactWidgetProps<T extends object | string = object> {
value: T // Current deserialized value
onChange: (value: T) => void // Update value and trigger re-render
inputName: string // Node input name
node: any // LGraphNode instance
widget: DOMWidget // DOMWidget instance for this widget
app: ComfyApp // ComfyApp instance
}
```
#### Receiving widget and node Information
```tsx
import type { ReactWidgetProps } from '@/lib/create-react-widget'
import type { DOMWidget } from '@comfyorg/comfyui-frontend-types'
export function MyWidget({ value, onChange, inputName, node, app, widget }: ReactWidgetProps) {
// node properties
const nodeId = node.id // Node unique ID
const nodeName = node.name // Node type name
const nodeType = node.type // Node class type
// widget properties
const widgetValue = widget.options?.serialize // widget serialization options
// app access
// app.ui, app.graph, app.commandMenu, etc.
return <div>...</div>
}
```
---
## Two-Way Data Binding Mechanism
### Internal Update (User Interacts with Component)
```
User interaction → onChange(newValue)
→ currentValue = JSON.stringify(newValue) // Persist
→ setDirtyCanvas(true, true) // Notify ComfyUI canvas to refresh
→ render() // Must call! Pass new props
```
### External Update (ComfyUI Loads Workflow/Undo/Redo)
```
ComfyUI calls setValue(jsonString)
→ currentValue = jsonString
→ render() // Re-render with new value
```
### Serialization (Building API Payload)
```
ComfyUI calls serializeValue()
→ Returns currentValue (JSON string)
```
---
## Key Considerations
### 1. Must Call render() After onChange
This is the most common bug. After `onChange` callback updates `currentValue`, you **must call `render()`** to pass the new value to the component. Otherwise the React component won't re-render (no state change triggers the update).
```ts
// Wrong: missing render(), component doesn't update
onChange: (v: T) => {
currentValue = JSON.stringify(v)
comfyNode.setDirtyCanvas(true, true)
}
// Correct
onChange: (v: T) => {
currentValue = JSON.stringify(v)
comfyNode.setDirtyCanvas(true, true)
render()
}
```
### 2. Derive Main Data from value Prop, Don't Use useState
The main data (i.e., data to be serialized to ComfyUI) must be read from the `value` prop, not stored in React state. Reason: ComfyUI may externally update values via `setValue` (loading workflows, undo, etc.), and React must render with new props.
```tsx
// Wrong: storing main data in state, external setValue won't sync
const [items, setItems] = useState(value)
// Correct: derive directly from value
const items = Array.isArray(value) ? value : []
```
`useState` is only for UI temporary state (e.g., draft values in input fields) that doesn't affect serialized data.
### 3. Defensive Parsing of value
When `defaultValue` is an empty string, `parseValue` returns the empty string instead of an empty array/object, so defensive handling is needed in components:
```tsx
const items: MyItem[] = Array.isArray(value) ? value : []
const data: MyData = value && typeof value === 'object' ? value as MyData : { text: '' }
```
### 4. Use Top-Level await + Dynamic Import in Entry Point
`src/index.ts` uses `await Promise.all([...dynamic imports...])` to load modules, ensuring React and widget code are code-split by Bun into separate chunks to avoid bloating the ComfyUI main JS bundle.
```ts
// Dynamic import, triggers Bun code splitting
const [{ createReactWidget }, { MyWidget }] = await Promise.all([
import('@/lib/create-react-widget'),
import('@/components/widgets'),
])
```
### 5. getCustomWidgets Key Must Match Python Type Name
The type string in Python `INPUT_TYPES` (e.g., `"MY_WIDGET"`) must exactly match the key in the object returned by `getCustomWidgets()`.
---
## Complete Example Reference
### React Component (`src/components/widgets/ColorPaletteWidget.tsx`)
```tsx
import { useState } from 'react'
import { Button } from '@/components/ui/button'
import { Input } from '@/components/ui/input'
import { uuid } from '@/lib/uuid'
import type { ReactWidgetProps } from '@/lib/create-react-widget'
export interface ColorPreset {
id: string
name: string
hexColor: string
}
export function ColorPaletteWidget({ value, onChange }: ReactWidgetProps<ColorPreset[]>) {
// Main data derived from value
const presets: ColorPreset[] = Array.isArray(value) ? value : []
// UI temporary state can use useState
const [newName, setNewName] = useState('')
function addPreset() {
if (!newName.trim()) return
onChange([...presets, {
id: uuid(),
name: newName.trim(),
hexColor: '#000000',
}])
setNewName('')
}
function removePreset(id: string) {
onChange(presets.filter(preset => preset.id !== id))
}
function updatePreset(id: string, patch: Partial<ColorPreset>) {
onChange(presets.map(preset => preset.id === id ? { ...preset, ...patch } : preset))
}
return (
<div className="flex flex-col gap-2 p-2 text-sm">
{/* ... JSX ... */}
</div>
)
}
```
### Entry Registration (`src/index.ts`)
```ts
const [{ createReactWidget }, { ColorPaletteWidget }] = await Promise.all([
import('@/lib/create-react-widget'),
import('@/components/widgets'),
])
globalThis.comfyAPI!.app.app.registerExtension({
name: 'EasyMedia.widgets',
async setup() {
addStylesheet(`/${import.meta.env.PROJECT_NAME}/globals.css`)
},
getCustomWidgets() {
return {
COLOR_PALETTE: createReactWidget<ColorPreset[]>(ColorPaletteWidget, {
defaultValue: JSON.stringify([]),
domWidgetOptions: { getMinHeight: () => 100 },
}),
}
},
})
```
---
## Debugging Checklist
| Symptom | Cause | Solution |
|---------|-------|----------|
| Component doesn't update after user action | `onChange` missing `render()` | Add `render()` at end of `onChange` |
| Shows old data after loading workflow | Main data stored in `useState` | Derive from `value` prop instead |
| Node value always empty | `defaultValue` not set or type name mismatch | Check `createReactWidget` `defaultValue` and Python type name |
| Widget height is 0 | `getMinHeight` not set | Set `getMinHeight` in `domWidgetOptions` |
| Styles not applying | CSS not loaded | Confirm `addStylesheet` is called in `setup()` |
---
## Localization (i18n)
All static text in widget components (labels, titles, placeholders, tooltips, context-menu items, aria-labels) **must** use the localization system instead of hardcoded strings.
### How It Works
The current ComfyUI locale is read from `app?.ui?.settings?.settingsValues?.['Comfy.Locale']` in the top-level widget component and provided via `LocaleContext`. Child components consume it with `useT()`.
Message catalogs live in `frontend/messages/`:
```
frontend/messages/
en.json ← English (fallback)
zh.json ← Chinese
```
Keys are organized by section (one section per component). Parameterized strings use `{name}` placeholders.
### 1. Add Keys to Both Catalogs
```jsonc
// messages/en.json
{
"myWidget": {
"addItem": "Add item",
"deleteItem": "Delete item",
"itemLabel": "Item {n}",
"placeholder": "Enter text…"
}
}
// messages/zh.json
{
"myWidget": {
"addItem": "添加项目",
"deleteItem": "删除项目",
"itemLabel": "项目 {n}",
"placeholder": "请输入文字…"
}
}
```
### 2. Provide Locale in the Top-Level Widget Component
Only the root `*Widget.tsx` component does this. Pass the raw locale string to `LocaleContext.Provider`:
```tsx
// src/components/widgets/MyWidget.tsx
import { LocaleContext } from '@/lib/i18n'
export function MyWidget({ value, onChange, app }: ReactWidgetProps<MyData>) {
const locale = app?.ui?.settings?.settingsValues?.['Comfy.Locale']
return (
<LocaleContext.Provider value={locale}>
{/* child components */}
</LocaleContext.Provider>
)
}
```
### 3. Consume in Any Child Component
```tsx
// src/components/widgets/timeline/MyTrack.tsx
import { useT } from '@/lib/i18n'
export function MyTrack() {
const t = useT()
return (
<div>
{/* Simple key */}
<Button>{t('myWidget.addItem')}</Button>
{/* With parameter */}
<span>{t('myWidget.itemLabel', { n: 3 })}</span>
{/* en → "Item 3" zh → "项目 3" */}
{/* Placeholder */}
<Textarea placeholder={t('myWidget.placeholder')} />
{/* Aria-label */}
<button aria-label={t('myWidget.deleteItem')} />
</div>
)
}
```
### 4. Common Shared Keys
Keys in the `"common"` section are shared across all components:
| Key | en | zh |
|-----|----|----|
| `common.cancel` | Cancel | 取消 |
| `common.save` | Save | 保存 |
| `common.add` | Add | 添加 |
| `common.delete` | Delete | 删除 |
```tsx
const t = useT()
<Button>{t('common.cancel')}</Button>
```
### Rule
> Every widget component that renders static text **must** call `useT()` and reference a message key.
> Hardcoded strings in JSX or props are not allowed.