> ## Documentation Index
> Fetch the complete documentation index at: https://dripart-docs-custom-nodes-sdk-v2-frontend.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<CardGroup cols={2}>
  <Card title="Main concepts" icon="lightbulb" href="/custom-nodes/v2/javascript/concepts">
    Learn handles, lifecycle, snapshots, capabilities, and how the frontend API is structured.
  </Card>

  <Card title="Extend a node with JavaScript" icon="graduation-cap" href="/custom-nodes/v2/javascript/tutorial">
    Follow a complete tutorial that adds a badge, a menu action, and lifecycle behavior to an existing node.
  </Card>

  <Card title="How-to guides" icon="list-check" href="/custom-nodes/v2/javascript/registration">
    Find focused guides for registration, definitions, graphs, slots, widgets, UI, execution, and services.
  </Card>

  <Card title="Reference" icon="book" href="/custom-nodes/v2/reference-overview">
    Look up imports, common patterns, rules, versioning, and exact API signatures.
  </Card>
</CardGroup>

## 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.

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

## 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.

```javascript theme={null}
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/`.

```text theme={null}
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](/custom-nodes/v2/javascript/migration-recipes) 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.

<Tip>
  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.
</Tip>

## Where to go next

1. Read [Use JavaScript handles and lifecycle](/custom-nodes/v2/javascript/concepts) for the frontend mental model.
2. Follow the [Extend a node with JavaScript](/custom-nodes/v2/javascript/tutorial) tutorial.
3. Study the [example packs](/custom-nodes/v2/javascript/example-packs) for tested, runnable patterns.
4. Use the focused [JavaScript how-to guides](/custom-nodes/v2/javascript/registration) while building a real pack.
5. Open the [Reference overview](/custom-nodes/v2/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.