Overview

Build JavaScript extensions for ComfyUI nodes with the published frontend API.

The Custom Nodes V2 frontend SDK is the published JavaScript API for extending ComfyUI node behavior, widgets, graphs, and interface features.

A pack’s frontend extension can:

• extend node definitions with custom behavior, badges, previews, and lifecycle hooks;
• add widgets, panels, menus, commands, and other interface features;
• read and edit graphs, nodes, slots, and links through documented handles;
• drive queueing, execution feedback, settings, storage, and authenticated backend requests.

This section documents the JavaScript API only. Python node authoring is documented separately.

Main concepts

Learn handles, lifecycle, snapshots, capabilities, and how the frontend API is structured.

Extend a node with JavaScript

Follow a complete tutorial that adds a badge, a menu action, and lifecycle behavior to an existing node.

How-to guides

Find focused guides for registration, definitions, graphs, slots, widgets, UI, execution, and services.

Reference

Look up imports, common patterns, rules, versioning, and exact API signatures.

What you can build

Anyone who can write JavaScript can change how a node looks and behaves in the ComfyUI editor: custom widgets, live previews, node badges, context menus, commands, panels, and graph automation.

Almost any frontend behavior built against app, LiteGraph, or prototype patching has a path to V2. Keep the behavior users rely on while replacing private implementation hooks with documented handles, events, and UI contributions.

You bring the user experience. Comfy provides the editor, the graph model, and a stable extension API.

How the API fits together

Part	Import	Use it for
JavaScript comfy	import { comfy } from '/comfy/api/v2.js'	Node definitions, graphs, nodes, slots, widgets, queueing, commands, settings, storage, backend calls, and UI

The normal authoring flow is:

1. Ship the extension module inside the pack’s v2/web/ distribution.
2. Import comfy from /comfy/api/v2.js.
3. Declare hard dependencies with comfy.require() and probe optional ones with comfy.supports().
4. Extend a node definition and attach lifecycle, widget, and UI behavior.
5. Read and mutate graph state through documented handles instead of private objects.

Extend a node through comfy

The JavaScript API represents ComfyUI nodes, graphs, widgets, and services through documented handles. Use those handles instead of patching private application objects.

import { comfy } from '/comfy/api/v2.js'

comfy.defs.extend('ScaleImage', (definition) => {
  definition.onCreated((node) => {
    node.addBadge(() => ({ text: 'V2' }))
  })
})

This keeps node behavior consistent as ComfyUI evolves and across supported frontend renderers.

V1 and V2 pack layout

A converted pack keeps its existing V1 distribution at the top level and adds a complete V2 replacement under v2/.

my_pack/
├── __init__.py                 # V1
├── nodes/                      # V1
├── web/                        # V1
└── v2/
    ├── __init__.py             # V2
    ├── nodes/                  # V2
    └── web/                    # V2

The host selects either the top level as the V1 pack root or v2/ as the V2 pack root. It does not merge the two trees or fall back to a V1 file that is missing from v2/.

V2 frontend modules and their assets live under v2/web/. A similarly named file in the root web/ tree is not a V2 asset.

For an existing pack, the recommended migration path is MAGIC PATCH, a local conversion tool that drives Claude Code or Codex on your own machine. See Migrate legacy frontend code for the frontend mappings it produces.

Build durable node code

Use documented comfy handles, events, and UI contributions instead of depending on window.app, LiteGraph internals, application stores, or host DOM. Published extension points can be versioned, tested, and kept compatible as ComfyUI evolves.

Avoid monkeypatching frontend prototypes, application stores, or the web page. Those changes depend on private implementation details and can break without notice. Prefer a published comfy capability. If the API cannot express a legitimate use case, tell us what extension point is missing. We expect to add capabilities as node authors find new needs. Keep any unavoidable private integration optional and separate from the main V2 path.

Where to go next

1. Read Use JavaScript handles and lifecycle for the frontend mental model.
2. Follow the Extend a node with JavaScript tutorial.
3. Study the example packs for tested, runnable patterns.
4. Use the focused JavaScript how-to guides while building a real pack.
5. Open the Reference overview when you need a rule or exact signature.

The generated API reference comes from comfy-api.d.ts. If prose and a generated signature disagree, follow the declaration and report the documentation mismatch.