ComfyUI SDK

Features

Installation

npm install comfyui-node

Quick Start

import { ComfyApi, Workflow } from 'comfyui-node';
import BaseWorkflow from './example-txt2img-workflow.json';
const api = await new ComfyApi('http://127.0.0.1:8188').ready();
const wf = Workflow.from(BaseWorkflow)
 .set('6.inputs.text', 'A dramatic cinematic landscape')
 .output('images:9');
const job = await api.run(wf, { autoDestroy: true });
job.on('progress_pct', p => console.log(`${p}%`));
const result = await job.done();
for (const img of (result.images?.images || [])) {
 console.log(api.ext.file.getPathImage(img));
}

Documentation

Getting Started

Multi-Instance Pooling

Advanced Features

Help & Migration

Key Concepts

Workflow vs PromptBuilder

const wf = Workflow.from(baseJson)
 .set('3.inputs.steps', 20)
 .input('SAMPLER', 'cfg', 4)
 .output('images:9');

const builder = new PromptBuilder(base, ['positive', 'seed'], ['images'])
 .setInputNode('positive', '6.inputs.text')
 .validateOutputMappings();

WorkflowPool

import { WorkflowPool, MemoryQueueAdapter, SmartFailoverStrategy } from "comfyui-node";
const pool = new WorkflowPool([
 new ComfyApi("http://localhost:8188"),
 new ComfyApi("http://localhost:8189")
], {
 failoverStrategy: new SmartFailoverStrategy({
 cooldownMs: 60_000, // Block workflow for 60s after failure
 maxFailuresBeforeBlock: 1 // Block on first failure
 }),
 healthCheckIntervalMs: 30000, // keeps connections alive
 enableProfiling: true, // NEW: enable automatic performance profiling
 executionStartTimeoutMs: 5000 // NEW: 5s timeout for execution to start
});
// Monitor job completion and view profiling stats
pool.on("job:completed", ev => {
 if (ev.detail.job.profileStats) {
 const { totalDuration, executionTime, summary } = ev.detail.job.profileStats;
 console.log(`Job ${ev.detail.job.jobId} completed in ${totalDuration}ms`);
 console.log(`Slowest nodes:`, summary.slowestNodes);
 }
});
const jobId = await pool.enqueue(workflow, { priority: 10 });

Advanced: MultiWorkflowPool for Heterogeneous Clusters

import { MultiWorkflowPool, Workflow } from "comfyui-node";
import SdxlWorkflow from './sdxl-workflow.json';
import VideoWorkflow from './video-workflow.json';
// 1. Define workflows and generate their hash for affinity mapping
const sdxlWF = Workflow.from(SdxlWorkflow).updateHash();
const videoWF = Workflow.from(VideoWorkflow).updateHash();
// 2. Create a new pool
const pool = new MultiWorkflowPool({
 logLevel: "info",
 enableMonitoring: true,
});
// 3. Add clients with workflow affinity
// This client is specialized for SDXL workflows
pool.addClient("http://localhost:8188", { workflowAffinity: [sdxlWF] });
// This client is specialized for Video workflows
pool.addClient("http://localhost:8189", { workflowAffinity: [videoWF] });
// This client is a general-purpose worker
pool.addClient("http://localhost:8190");
// 4. Initialize the pool (connects to all clients)
await pool.init();
// 5. Submit jobs
// The pool automatically routes them to the correct client
const sdxlJobId = await pool.submitJob(sdxlWF);
const videoJobId = await pool.submitJob(videoWF);
// 6. Wait for a job to complete
const results = await pool.waitForJobCompletion(sdxlJobId);
console.log("SDXL Job completed!", results.images);

What's New in v1.6.5

Examples

API Reference

ComfyApi Client

const api = new ComfyApi('http://127.0.0.1:8188', 'optional-id', {
 credentials: { type: 'basic', username: 'user', password: 'pass' },
 wsTimeout: 60000,
 comfyOrgApiKey: process.env.COMFY_ORG_API_KEY,
 debug: true
});
await api.ready(); // Connection + feature probing

Modular Features (api.ext)

await api.ext.queue.queuePrompt(null, workflow);
await api.ext.queue.interrupt();
const stats = await api.ext.system.getSystemStats();
const checkpoints = await api.ext.node.getCheckpoints();
await api.ext.file.uploadImage(buffer, 'image.png');
const history = await api.ext.history.getHistory('prompt-id');

Events

api.on('progress', ev => console.log(ev.detail.value, '/', ev.detail.max));
api.on('b_preview', ev => console.log('Preview:', ev.detail.size));
api.on('executed', ev => console.log('Node:', ev.detail.node));
job.on('progress_pct', pct => console.log(`${pct}%`));
job.on('preview', blob => console.log('Preview:', blob.size));
job.on('failed', err => console.error(err));

Testing

Unit and Integration Tests

bun test # Unit + integration tests
bun run test:integration # Run all integration tests
bun run test:integration:simple # Run simple reconnection examples
bun run test:real # Real server tests (COMFY_REAL=1)
bun run test:full # Comprehensive tests (COMFY_FULL=1)
bun run coverage # Coverage report

Integration Tests (v1.6.5+)

# Run all integration tests
bun test test/integration/
# Run simple examples (recommended first)
bun run test:integration:simple
# Validate the mock server infrastructure
bun test/integration/validate-mock-server.ts
# Debug: Run mock server standalone
bun test/integration/mock-server.ts 8191

// Integration test pattern
const manager = new ServerManager({ port: 8191 });
await manager.startServer(8191);
const api = new ComfyApi("http://localhost:8191");
await initializeClient(api);
// Kill server to simulate crash
await manager.killServer(8191);
await sleep(500);
// Restart server
await manager.startServer(8191);
// Verify reconnection
await api.reconnectWs(true);
await waitForConnection(api);
expect(api.isConnected()).toBe(true);
// Cleanup
api.destroy();
await manager.killAll();

Contributing

License

Links