/comfyui-node-registry

name: comfyui-node-registry
description: Authoring & publishing ComfyUI custom nodes to the Comfy Registry, covering node structure, pyproject.toml spec, comfy-cli publishing, and CI

Authoring & Publishing ComfyUI Custom Nodes

This skill covers writing a ComfyUI custom node pack and publishing it to the Comfy Registry (registry.comfy.org), the public catalog that powers ComfyUI-Manager. For *using* existing nodes in workflows, see the `comfyui-core` skill instead.

Minimal Node Pack Structure

A node pack is a Python package placed under `ComfyUI/custom_nodes/<name>/`. The package `__init__.py` must export `NODE_CLASS_MAPPINGS` and `NODE_DISPLAY_NAME_MAPPINGS`; `WEB_DIRECTORY` is optional (only if the pack ships frontend JS).

ComfyUI/custom_nodes/my-node-pack/
├── __init__.py          # exports the mappings ComfyUI scans for
├── nodes.py             # node class definitions
├── pyproject.toml       # registry metadata (required to publish)
├── requirements.txt     # optional Python deps
├── .comfyignore         # optional — exclude files from the published archive
├── LICENSE
├── README.md
└── web/js/              # optional frontend extension (see WEB_DIRECTORY)

`__init__.py`

from .nodes import NODE_CLASS_MAPPINGS, NODE_DISPLAY_NAME_MAPPINGS

# Optional: serve frontend JS/CSS from this folder (path relative to __init__.py)
WEB_DIRECTORY = "./web/js"

__all__ = ["NODE_CLASS_MAPPINGS", "NODE_DISPLAY_NAME_MAPPINGS", "WEB_DIRECTORY"]

A minimal node class (`nodes.py`)

class ImageSelector:
    CATEGORY = "example"          # menu path where the node appears

    @classmethod
    def INPUT_TYPES(cls):
        return {
            "required": {
                "images": ("IMAGE",),
                "mode": (["brightest", "reddest", "greenest", "bluest"],),
            },
            "optional": {
                "threshold": ("FLOAT", {"default": 0.5, "min": 0.0, "max": 1.0, "step": 0.01}),
                "count": ("INT", {"default": 1, "min": 1, "max": 64}),
                "label": ("STRING", {"default": "", "multiline": False}),
            },
        }

    RETURN_TYPES = ("IMAGE",)        # tuple of output data types
    RETURN_NAMES = ("image",)        # optional friendly output names
    FUNCTION = "choose_image"        # name of the method ComfyUI calls
    OUTPUT_NODE = False              # True for terminal nodes (e.g. SaveImage)

    def choose_image(self, images, mode, threshold=0.5, count=1, label=""):
        import torch
        brightness = [torch.mean(img.flatten()).item() for img in images]
        best = brightness.index(max(brightness))
        return (images[best].unsqueeze(0),)   # MUST return a tuple


NODE_CLASS_MAPPINGS = {
    "ImageSelector": ImageSelector,        # globally unique class_type key
}

NODE_DISPLAY_NAME_MAPPINGS = {
    "ImageSelector": "Image Selector",     # label shown in the UI
}

Node class contract

| Member | Required | Purpose | |--------|----------|---------| | `INPUT_TYPES` | yes | `@classmethod` returning `{"required": {...}, "optional": {...}}`. Each input is `(TYPE,)` or `(TYPE, {opts})`. | | `RETURN_TYPES` | yes | Tuple of output type strings (e.g. `("IMAGE", "MASK")`). Single output still needs a trailing comma. | | `FUNCTION` | yes | String name of the method to execute. | | `CATEGORY` | yes | Menu path string for the Add Node menu. | | `RETURN_NAMES` | no | Friendly names for outputs (defaults to lowercased types). | | `OUTPUT_NODE` | no | `True` marks a terminal node that produces a result (save/preview). |

The options dict drives the UI widget for each input type:

• `("INT", {"default": 0, "min": 0, "max": 100, "step": 1})`
• `("FLOAT", {"default": 1.0, "min": 0.0, "max": 10.0, "step": 0.1})`
• `("STRING", {"default": "", "multiline": True})`
• `(["a", "b", "c"],)`, a literal list, becomes a dropdown
• `("IMAGE",)`, `("LATENT",)`, `("MODEL",)` etc. are typed connections (no widget)

The executing method must return a tuple matching `RETURN_TYPES`, even for a single output (`return (result,)`).

`pyproject.toml` — Registry Metadata

Required to publish. `comfy node init` scaffolds this file. See `references/pyproject.toml` for a fully-commented example.

[project]
name = "my-node-pack"                          # unique & IMMUTABLE; lowercase, <100 chars, no "ComfyUI" prefix
description = "What this node pack does"
version = "1.0.0"                              # semantic version X.Y.Z — bump to publish a new version
license = { file = "LICENSE" }                 # or { text = "MIT License" }
requires-python = ">=3.10"
dependencies = [
    "comfyui-frontend-package<=1.21.6",        # optional — pin frontend if you ship UI
]
classifiers = [
    "Operating System :: OS Independent",
]

[project.urls]
Repository = "https://github.com/you/my-node-pack"   # REQUIRED — must be a valid repo URL
Documentation = "https://github.com/you/my-node-pack/wiki"
"Bug Tracker" = "https://github.com/you/my-node-pack/issues"

[tool.comfy]
PublisherId = "your-publisher-id"              # the id after @ on your registry profile
DisplayName = "My Node Pack"                   # human-friendly name in the registry
Icon = "https://raw.githubusercontent.com/you/my-node-pack/main/icon.png"   # square, max 400x400px
requires-comfyui = ">=1.0.0"                   # optional ComfyUI version constraint

Field rules (verified against the live spec)

| Field | Section | Notes | |-------|---------|-------| | `name` | `[project]` | **Unique and immutable** once published. <100 chars; alphanumeric + `-` `_` `.`; no consecutive special chars; can't start with a number/special char; case-insensitive. Don't prefix with "ComfyUI". | | `version` | `[project]` | **Semantic** `X.Y.Z` — X breaking, Y backwards-compatible feature, Z bug fix. Each value is published **once** and is immutable. | | `description` | `[project]` | Short summary (recommended). | | `license` | `[project]` | `{ file = "LI