Reference overview - ComfyUI

Use this section when you already understand the V2 model and need an exact import, signature, rule, or API surface.

Imports

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

comfy.version reports the contract as major.minor. Keep a released pack on a supported major with comfy.forMajor().

Pack layout

my_pack/
├── <complete V1 distribution>
└── v2/
    └── <complete V2 replacement distribution>

The top level remains the V1 pack root. v2/ is the V2 pack root, not a patch directory. V2 does not merge with or fall back to V1.

Minimal JavaScript pattern

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

comfy.require('defs.extend')

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

Core rules

Rule	Meaning
Treat returned data as snapshots	Ask the API again when current frontend state matters.
Check `isDeleted` before reuse	A handle can outlive the node, widget, or document session it describes.
Mutate through handles	Use documented methods so validation, events, undo, and serialization remain consistent.
Probe optional capabilities	Use `supports()` for enhancements and `require()` for hard dependencies.
Avoid private monkeypatches	Private server or web-page internals are not part of the versioned API contract.

JavaScript reference

When something is missing

Report the user-visible behavior, affected JavaScript surface, current workaround, and why existing APIs are insufficient. New capabilities and extension points can be added for legitimate author needs. Keep any temporary private integration optional and local-only.