Build a Custom ComfyUI Node

ComfyUI’s power comes from its node-based architecture. Each node is a Python class that receives inputs, processes them, and passes outputs to the next node in the graph.

Custom nodes let you extend ComfyUI with your own logic — anything from text manipulation to image filters to API calls. They live in the custom_nodes/ directory and are loaded automatically on startup.

Why Build Custom Nodes?

• Add pre-processing or post-processing steps to your workflow
• Integrate external APIs or local tools
• Create reusable building blocks for complex pipelines
• Share functionality with the ComfyUI community

A real-world example is the ThumperPromptEnhance node, which uses a local Qwen3-4B model to rewrite short prompts into detailed image descriptions — replacing a 10+ minute Gemma 12B pipeline with a ~40-second alternative.

Each custom node lives in its own folder inside ComfyUI’s custom_nodes/ directory. Create a new folder for your node:

# Navigate to your ComfyUI installation
cd ~/.local/share/tr-desktop/apps/comfyui/
 
# Create the custom node directory
mkdir -p custom_nodes/my_text_tools

The directory name becomes the node pack’s identifier. Use snake_case for consistency with the ComfyUI ecosystem.

Directory Structure

A minimal custom node needs just one file:

custom_nodes/
  my_text_tools/
    __init__.py       # Node class + registration

Larger node packs may split logic across multiple files, but the entry point is always __init__.py.

Open custom_nodes/my_text_tools/__init__.py in your editor and paste the following:

class TextToUppercase:
    """Converts input text to uppercase."""
 
    @classmethod
    def INPUT_TYPES(cls):
        return {
            "required": {
                "text": ("STRING", {
                    "multiline": True,
                    "default": "hello world"
                }),
            }
        }
 
    RETURN_TYPES = ("STRING",)
    RETURN_NAMES = ("upper_text",)
    FUNCTION = "to_upper"
    CATEGORY = "text"
 
    def to_upper(self, text):
        return (text.upper(),)
 
# --- Registration (required) ---
NODE_CLASS_MAPPINGS = {
    "TextToUppercase": TextToUppercase,
}
 
NODE_DISPLAY_NAME_MAPPINGS = {
    "TextToUppercase": "Text to Uppercase",
}

Anatomy of a Node Class

• INPUT_TYPES — classmethod that declares what inputs the node accepts and their types
• RETURN_TYPES — tuple of output type strings (e.g. "STRING", "IMAGE", "INT")
• RETURN_NAMES — human-readable labels for each output
• FUNCTION — name of the method ComfyUI calls when executing the node
• CATEGORY — determines where the node appears in the Add Node menu

Registration Dictionaries

Every __init__.py must export two dictionaries:

• NODE_CLASS_MAPPINGS — maps unique node IDs to their Python classes
• NODE_DISPLAY_NAME_MAPPINGS — maps node IDs to display names shown in the UI

ComfyUI discovers custom nodes at startup. To load your new node:

1. If ComfyUI is running, stop it from the Thumper-Run dashboard
2. Relaunch ComfyUI — click Launch on the ComfyUI card
3. Once running, right-click the canvas and open Add Node → text
4. You should see Text to Uppercase in the list. Click it to place a new node on the canvas — it appears as a rectangular block with a text input field and an upper_text output socket.
5. Type some text in the input field, wire the output to another node (e.g. a "Show Text" node or a CLIP text encoder), and click Queue Prompt to run it

Debugging

If your node doesn’t appear:

• Check the ComfyUI console output for import errors
• Verify NODE_CLASS_MAPPINGS is defined at module level (not inside a function)
• Ensure the directory has an __init__.py file (not just a .py script)
• Confirm the file has no syntax errors: python -c "import my_text_tools"

Testing the Output

To verify your node works, connect it to a "Show Text" node (if installed) or check the execution API response. A quick test:

# Queue the workflow and check the output in the API response
curl -s http://localhost:8188/history | python -m json.tool | head -20