ComfyUI V3 Custom Nodes (Server-Side)

Scope

• Focus on server-side V3 nodes (Python).
• Exclude client-server extension patterns and frontend-only extensions.

Quick Workflow

1. Choose API adapter:

   comfy_api.v0_0_2

   for stability or

   comfy_api.latest

   for newest features.
2. (Optional) Scaffold a nodepack using

   comfy node scaffold

   .
3. Implement a V3 node with

   io.ComfyNode.define_schema()

   and

   execute()

   .
4. Return

   io.NodeOutput

   (or tuple/dict) from

   execute()

   .
5. Register nodes via

   ComfyExtension.get_node_list()

   and

   comfy_entrypoint()

   .
6. Restart ComfyUI and validate in UI/API.

Do / Don’t

• Do use classmethods

  define_schema()

  and

  execute()

  .
• Do return

  io.NodeOutput

  (or tuple/dict) from

  execute()

  .
• Do use

  ui.Preview*

  helpers for UI previews.
• Don’t store mutable instance state in nodes.
• Don’t use client-server extension patterns (out of scope for this skill).

Reference Map

• references/v3-core.md

  : API versions, ComfyExtension, progress reporting.

• references/io-types.md

  : IO types, widget inputs, custom types.

• references/schema-nodeoutput.md

  : Schema fields, flags, hidden inputs, NodeOutput patterns.

• references/ui-helpers.md

  : Preview and save helpers for UI outputs.

• references/scaffold.md

  : Scaffold workflow and V3 defaults.

• references/lazy-evaluation.md

  : Lazy inputs, check_lazy_status, execution blocking.

• references/validation-and-caching.md

  : validate_inputs and fingerprint_inputs patterns.

• references/folder-paths-and-files.md

  : folder_paths helpers and save/load patterns.

• references/image-mask-performance.md

  : Tensor shapes, resizing, batching, device tips.
• Official docs: Comfy-Org/docs custom-nodes

Template

• assets/v3_extension_template.py

  : Minimal V3 node + extension + entrypoint.