Skip to main content
A pack selects a filesystem version, and the JavaScript API then reports its own contract version and capability grants.

​
Pack filesystem versions

The pack’s filesystem version is selected before either language API loads. A converted pack retains its complete V1 distribution at the pack root and stores its complete replacement V2 distribution under v2/.
The v2/ directory is a replacement pack root, not a patch or overlay and not the Python API module name. It is generally copied from the top-level distribution before conversion. When selected, frontend modules inside it import /comfy/api/v2.js. Keep version-specific entrypoints, dependencies, assets, and metadata inside their respective distribution trees; do not rely on fallback to V1.

​
JavaScript versions

Import the published module directly:
comfy.version reports the contract as major.minor. A major change can remove behavior. A minor change only adds behavior. comfy.forMajor(major) keeps a pack on a supported major during a deprecation period. Do not branch on a version string when you need one feature. Backports and grant policy can make a version comparison inaccurate.

​
Probe a capability

supports() is cheap and does not throw. Its answer includes both host support and the current pack grant. Use require() when the extension has no useful behavior without the feature:
Use comfy.capabilities() for diagnostics or a compatibility report, not to request everything the host offers.
Capability discovery does not grant authority. A pack should declare the narrow set it needs and continue without optional enhancements when possible.

​
Request a missing capability

The V2 API is intended to grow with real node-author needs. If a useful node cannot be implemented through the published surface, report the missing operation or extension point instead of building a permanent dependency on private ComfyUI internals. A useful capability request includes:
  • the user-visible behavior the node is trying to provide;
  • the old API, private object, or monkeypatch currently used;
  • why existing refs, context services, handles, hooks, or UI contributions are insufficient;
  • whether the capability is required or an optional enhancement;
  • a small example showing the desired author-facing API when practical.
New capabilities should express the useful outcome without exposing unrelated application internals. Until one is available, keep the workaround clearly optional so the main V2 behavior does not depend on a private implementation detail.

​
Handle API generations

Two handles can describe the same entity while coming from different API instances, graph scopes, or majors. Compare them with comfy.sameEntity():
Use comfy.adopt(handle) to re-resolve a node handle into the current API instance. It returns undefined when the value is not a node handle or the entity is gone.

​
Compatibility policy for a pack

  1. Import /comfy/api/v2.js and require only hard dependencies.
  2. Probe optional enhancements individually with supports().
  3. Keep a released pack on a supported major with comfy.forMajor().
  4. Treat an ungranted capability as unavailable rather than reaching for a private equivalent.
  5. Never fall back to a private import, global object, path, or DOM selector.
  6. Report a named API gap and its user-visible use case when the supported surface cannot express required behavior.