comfyui-node-organizer

ComfyUI Node Organizer

Automatically organizes ComfyUI workflows with a compact group-aware layout. Created with comfyui-custom-node-template.

Preview of organizing a workflow

<img src="assets/preview.gif" alt="User clicking on the Organize Workflow context menu item" loop=infinite>

Preview of organizing groups with tokens

<img src="assets/preview-tokens.gif" alt="User clicking on different groups and seeing the nodes arranged according to the tokens" loop=infinite>

Installation

1. Open ComfyUI
2. Go to Manager > Custom Node Manager
3. Search for Node Organizer
4. Click Install

Usage

Use any of these entry points:

• Right-click the canvas and choose Organize Workflow
• Select groups and choose Organize Group
• Click the Organize action-bar button
• Use Extensions > Node Organizer
• Press Shift+O

Group Layout Tokens

Add tokens to group titles to control how nodes are arranged:

| Token | Effect | |-------|--------| | [HORIZONTAL] | Single horizontal row | | [VERTICAL] | Single vertical column | | [2ROW]...[9ROW] | Distribute into N rows | | [2COL]...[9COL] | Distribute into N columns |

Examples:

• "My Loaders [HORIZONTAL]" - arranges all nodes in a single row

• "Processing [3COL]" - distributes nodes into 3 columns

• Tokens are case-insensitive ([horizontal] works)

• [1ROW] = [HORIZONTAL], [1COL] = [VERTICAL]

• Nested groups each respect their own tokens

• Groups without tokens use default DAG-based layout

Testing

• pnpm typecheck
• pnpm test
• pnpm build
• pnpm build:lib emits the pure library entrypoint to lib/
• pnpm test:lib smoke-tests the built comfyui-node-organizer npm export
• pnpm setup:e2e provisions a dedicated ComfyUI instance for browser tests and installs the exact workflow-template package required by the pinned ComfyUI checkout
• pnpm test:e2e runs the full Playwright suite against that instance
• Broad installed-template coverage is discovered live at E2E runtime from the pinned test ComfyUI environment, with one correctness-invariant test per installed workflow template

Checked-in repo fixtures live in tests/fixtures/. Visual regression is graph-canvas scoped and runs as part of the normal E2E suite. Visual regression baselines are platform-specific: committed snapshots use -win32 and -linux suffixes.

Library API

Most users can ignore this section. The extension works entirely inside ComfyUI.

The package is published to npm as comfyui-node-organizer for developers who want to reuse the layout engine outside ComfyUI, for example in a script, service, test harness, or workflow conversion tool.

npm install comfyui-node-organizer

import { normalizeWorkflowGeometry, inferGroupMembership } from "comfyui-node-organizer";

It exposes a small pure API:

• normalizeWorkflowGeometry(...) lays out plain workflow data and returns absolute node and group rectangles
• inferGroupMembership(...) infers direct group membership from node and group rectangles

In practice: if you want "organize this workflow JSON the same way the extension would" without loading ComfyUI, this is the entrypoint.

Build it locally with pnpm build:lib. pnpm test:lib verifies that the built package can be imported by Node.

Local CI

Install act and Docker, then run:

• pnpm ci:local runs the full local CI workflow with act

Release

Maintainer flow:

• Merge the release branch into main
• Trigger .github/workflows/publish_action.yaml manually from main

That workflow runs the full test suite, bumps versioned files with uv run bump-my-version, creates the tag and GitHub release, then publishes the custom node from the bumped tag ref.

Manual browser testing

Build the extension first so ComfyUI loads the current dist/ output:

• pnpm build

Launch the test ComfyUI instance on a free port:

• .test-comfy/venv/Scripts/comfy.exe --skip-prompt --workspace .test-comfy/comfyui/ launch -- --cpu --port 65192

If the port is already taken, either choose a different port or stop leftover test-instance processes first:

• Get-Process | Where-Object { $_.Path -like '*comfy-node-organizer\\.test-comfy*' } | Stop-Process -Force

Known Limitations

Very large or unusual workflows may still expose edge cases. If you hit one, please open a GitHub issue with a minimal reproducible workflow attached.