npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

comfy-api-helper

v2.0.1

Published

A Typescript helper library to make using the ComfyUI API easier

Readme

Comfy API Helper

A lightweight TypeScript helper library for generating images from a local ComfyUI instance.

Version 2.0.0 introduces a simpler, more reliable execution model built around ComfyUI's WebSocket events instead of queue/history polling. This makes repeated identical workflow runs work correctly, including cached executions.

What's new in 2.0

  • Switched to WebSocket-based execution tracking
  • Properly correlates requests with ComfyUI using clientId / client_id
  • Handles cached workflow executions correctly
  • Clearer user-facing error messages for:
    • connection failures
    • malformed/rejected workflows
    • workflows that run but do not produce usable image outputs
  • Refactored internal structure into:
    • src/index.ts
    • src/helpers.ts
    • src/types.ts

Installation

Using npm:

npm install comfy-api-helper

Using Bun:

bun add comfy-api-helper

Using pnpm:

pnpm add comfy-api-helper

Requirements

  • Node.js >=18
  • A running ComfyUI instance
  • A workflow exported from ComfyUI in API format
  • Any models and custom nodes required by that workflow installed in your ComfyUI instance

Quick start

Export a workflow from ComfyUI using:

  • File -> Export (API)

Then call generateImages(...) with that workflow object and your ComfyUI endpoint.

import fs from 'fs';
import { generateImages } from 'comfy-api-helper';
import workflow from './workflow.json' with { type: 'json' };

const COMFY_ENDPOINT = 'http://127.0.0.1:8188';

const images = await generateImages(workflow, COMFY_ENDPOINT);
fs.writeFileSync('output.png', images[0]);

Usage

This library is designed for workflows that produce one or more saved or previewed image outputs.

If you want to modify prompts, checkpoints, seeds, or other inputs programmatically, a good pattern is to wrap your exported workflow JSON in a small factory function.

Example: procedural workflow builder

import fs from 'fs';
import { generateImages } from 'comfy-api-helper';
import { workflowApiFactory } from './workflow';

const COMFY_ENDPOINT = 'http://127.0.0.1:8188';
const CHECKPOINT = 'Illustrious/novaAnimeXL_ilV120.safetensors';
const PROMPT =
  'cute anime girl with massive fluffy fennec ears and a big fluffy tail';

const workflow = workflowApiFactory(PROMPT, CHECKPOINT);
const images = await generateImages(workflow, COMFY_ENDPOINT);

fs.writeFileSync('output.png', images[0]);

Example: direct workflow JSON

import fs from 'fs';
import { generateImages } from 'comfy-api-helper';
import workflow from './workflow.json' with { type: 'json' };

const COMFY_ENDPOINT = 'http://127.0.0.1:8188';

const images = await generateImages(workflow, COMFY_ENDPOINT);
fs.writeFileSync('output.png', images[0]);

See the example/ directory for a working end-to-end example.

API

generateImages(workflow, comfyEndpoint, outputFormat?)

Generates one or more images and returns them as buffers.

Parameters

  • workflow
    • A ComfyUI workflow object exported with File -> Export (API)
  • comfyEndpoint
    • Your ComfyUI server URL, for example http://127.0.0.1:8188
  • outputFormat
    • Optional
    • 'png' | 'webp'
    • Defaults to 'png'

Returns

Promise<Buffer[]>

Notes

  • Returns an array because a workflow may produce multiple images
  • The workflow must produce at least one saved or previewed image output
  • Output images are normalized to either png or webp

generateImageToDataUri(workflow, comfyEndpoint, outputFormat?)

Generates images and returns them as data URIs.

Returns

Promise<string[]>

Useful for directly assigning to image tags in web apps.

generateImageToBase64String(workflow, comfyEndpoint, outputFormat?)

Generates images and returns them as raw base64 strings.

Returns

Promise<string[]>

Error handling

This library throws ComfyApiError with user-facing messages intended to explain what went wrong and how to fix it.

Connection failed

Example causes:

  • ComfyUI is not running
  • the endpoint URL is wrong
  • the connection dropped during execution

Example message:

Could not connect to ComfyUI at "http://127.0.0.1:8188". Make sure ComfyUI is running and that the endpoint URL is correct.

Malformed workflow

Example causes:

  • the workflow object is invalid or empty
  • the workflow was not exported in API format
  • ComfyUI rejected the workflow because a model or node input is invalid
  • required custom nodes or models are missing

When ComfyUI returns structured validation errors, the library formats them into a more readable message.

Example:

The provided workflow is malformed or incompatible with your ComfyUI setup, so ComfyUI rejected it. Make sure you exported the workflow using File -> Export (API), and that all required nodes and models are installed.

ComfyUI said:
Prompt outputs failed validation
- CheckpointLoaderSimple 4 for output 10: ckpt_name: 'bad-model-name.safetensors' not in [...]
ComfyUI error type: prompt_outputs_failed_validation

Unsupported workflow output

Example causes:

  • the workflow completed but did not save or preview any images
  • ComfyUI reported image output metadata that could not be used
  • the generated image could not be downloaded or converted

Example message:

The workflow ran in ComfyUI, but this script could not extract an image from it. No image outputs were reported during execution. This usually means the workflow does not save or preview any images. To use this script, the workflow must produce at least one saved or previewed image output.

Migration notes from 1.x

Version 2.0 includes a few important behavior changes:

  • generateImage(...) has been replaced by generateImages(...)
  • return values are now arrays:
    • Promise<Buffer[]>
    • Promise<string[]>
  • execution tracking now uses WebSocket events instead of queue/history polling
  • repeated identical workflow submissions now work correctly with ComfyUI caching

If you previously expected a single image, update your code from:

const image = await generateImage(workflow, endpoint);
fs.writeFileSync('output.png', image);

to:

const images = await generateImages(workflow, endpoint);
fs.writeFileSync('output.png', images[0]);

Development

Build the package:

bun run build

Run the example locally:

bun run example/example.ts

The build outputs the distributable files to dist/.

Publishing

The package is configured so that publishing includes:

  • dist/**/*
  • README.md
  • LICENSE

A build runs automatically before publish via prepublishOnly.

License

MIT