5-minute quickstart

Two shortest paths. Pick one. Neither requires reading Graph IR first.

Path A — you already have workflow JSON

pnpm add @stepupgaming/comfy-workflows
cwf init my-workflow --from workflow.json
cd my-workflow
cwf pack
cwf inspect . --url http://127.0.0.1:8188

cwf init writes package.json, comfy.workflow.json, workflow.ir.json, and an editable workflow.ts. Inspect reads the JSON as data. It does not execute package JS.

Full walkthrough: Import workflow JSON.

Path B — you want TypeScript from scratch

You need a running Comfy at http://127.0.0.1:8188 or a saved object_info.json.

pnpm add @stepupgaming/comfy-workflows
cwf snapshot --url http://127.0.0.1:8188 -o object_info.json
cwf lock --url http://127.0.0.1:8188
cwf codegen --from object_info.json -o src/nodes/gen

Then author with the bundled core nodes (enough for SD1.x T2I) or the generated registry:

/**
 * Code-first quickstart graph. Edit this file; do not hand-edit compiled JSON.
 */
import { compile, workflow, type Graph } from "@stepupgaming/comfy-workflows";
import { conditioning, image, latent, loaders, sampling } from "@stepupgaming/comfy-workflows/nodes";

export function build(): Graph {
  const g = workflow("docs-t2i");

  const ckpt = g.add(loaders.CheckpointLoaderSimple, {
    ckpt_name: "v1-5-pruned-emaonly.safetensors",
  });
  const positive = g.add(conditioning.CLIPTextEncode, {
    text: "a red cube on a table, still camera",
    clip: ckpt.CLIP,
  });
  const negative = g.add(conditioning.CLIPTextEncode, {
    text: "blurry, text, watermark",
    clip: ckpt.CLIP,
  });
  const empty = g.add(latent.EmptyLatentImage, {
    width: 512,
    height: 512,
    batch_size: 1,
  });
  const sampled = g.add(sampling.KSampler, {
    model: ckpt.MODEL,
    positive: positive.CONDITIONING,
    negative: negative.CONDITIONING,
    latent_image: empty.LATENT,
    seed: 42n,
    steps: 8,
    cfg: 7,
    sampler_name: "euler",
    scheduler: "normal",
    denoise: 1,
  });
  const decoded = g.add(latent.VAEDecode, {
    samples: sampled.LATENT,
    vae: ckpt.VAE,
  });
  g.add(image.SaveImage, {
    images: decoded.IMAGE,
    filename_prefix: "docs-t2i",
  });
  g.output(decoded.IMAGE, { name: "image" });
  return g.toGraph();
}

export function compiledJson(): string {
  const result = compile(build());
  if (!result.ok) {
    throw new Error(result.errors.map((e) => `${e.code}: ${e.message}`).join("\n"));
  }
  return result.json;
}

cwf compile workflow.ts -o dist/prompt.json
cwf validate workflow.ts --url http://127.0.0.1:8188
cwf run workflow.ts --url http://127.0.0.1:8188 --out out/

Full walkthrough: Code-first quickstart.

Using a coding agent? After install, cwf agent install copies the SDK skill into .agents/skills/comfy-workflows/. Coding agents.

What you just learned

To change the graph, change TypeScript (or re-import JSON). Do not edit compiled API JSON. Do not edit workflow.ir.json by hand in a first-party package.

What do I edit?