ComfyUI Frontend React Extension Template

A template for building ComfyUI extensions using React 19, TypeScript, and Vite. Covers bottom panels, sidebar tabs, top bar menus, custom node widgets, and modal dialogs — all with theme-aware styling and full type safety.

Prerequisites

• Node.js 18+
• ComfyUI installed and running at http://127.0.0.1:8188

Quick Start

# 1. Clone into ComfyUI's custom_nodes directory
cd ComfyUI/custom_nodes
git clone <repository-url> my-extension

# 2. Install dependencies and build
cd my-extension/ui
npm install
npm run build

# 3. Restart ComfyUI — the extension loads automatically

Development

Start the Vite dev server for live reload:

cd ui
npm run dev

The dev server runs at http://localhost:5173. Vite rewrites /scripts/app.js and /scripts/api.js imports to http://127.0.0.1:8188/ so the extension connects to your running ComfyUI instance. Changes hot-reload without restarting ComfyUI.

| Command | Description | | ----------------- | ---------------------------------------------- | | npm run dev | Dev server with HMR | | npm run build | Production build to dist/ | | npm run watch | Continuous build (no HMR) | | npm run lint | ESLint | | npm run preview | Preview production build locally |

How It Works

Python Backend (__init__.py)

Registers the web directory with ComfyUI so it serves the built JS. Also defines example custom nodes (e.g., ButtonNode). Warns at startup if dist/ hasn't been built yet.

Frontend Entry Point (ui/src/main.tsx)

Calls comfy.registerExtension() with all hooks:

• beforeRegisterNodeDef — modify node prototypes before they're registered (add widgets, override methods)
• setup — runs after all nodes are registered (show toasts, register sidebar tabs)
• bottomPanelTabs — adds tabs to ComfyUI's bottom panel
• commands + menuCommands — adds items to the top bar menu

TypeScript Stubs

src/stubs/app.ts and src/stubs/api.ts provide type definitions for ComfyUI's internal APIs. Path aliases in tsconfig map /scripts/app.js → src/stubs/app so imports are fully typed:

import { app } from "/scripts/app.js";  // typed, works in both dev and production

Extension Points Demonstrated

| Feature | Where | | ------------------ | ------------------------------------ | | Bottom panel tab | bottomPanelTabs in main.tsx | | Sidebar tab | comfy.extensionManager.registerSidebarTab() in setup() | | Top bar menu | commands + menuCommands in main.tsx | | Node widget | beforeRegisterNodeDef in main.tsx | | Modal dialog | src/components/CounterDialog.tsx + src/utils/counter-dialog.ts |

Styling

Use ComfyUI CSS variables for automatic dark/light theme support. Always provide fallbacks:

style={{
  backgroundColor: "var(--secondary-background, #1f2937)",
  color: "var(--text-primary, #f9fafb)",
  borderColor: "var(--border-color, #374151)",
}}

Key variable groups: --base-background, --secondary-background, --text-primary, --text-secondary, --border-color, --primary-background, --color-accent-blue.

Resources

• AGENTS.md — Architecture guide and key patterns for agents
• ComfyUI
• ComfyUI React Extension Template (official)
• PrimeVue Icons — used for sidebar/menu icons (pi pi-*)