Managing Templates

Managing Templates

Covers adding new templates and renaming existing ones in this repository.

Related skills (do not replace this one):

• /managing-bundles — move between bundles / categories / order
• /managing-thumbnails — thumbnail-only work
• /managing-translations — broader i18n work
• /managing-mcp-index — MCP index only

Shared Rules

• Never modify scripts, build tooling, or CI configuration.
• Template names must be snake_case — no spaces, dots, or special characters.
• name must match the workflow JSON filename (without .json).
• Always run python3 scripts/sync/sync_bundles.py after editing bundles.json or renaming template assets.
• Always validate after structural changes (see Validation below).
• For new templates, assign media to media-assets-02 — see scripts/docs/frozen_bundles.md.
• Bump root pyproject.toml only for intentional PyPI releases (release label).
• Use double-quotes " in all JSON files.
• Model download URLs must produce filenames that exactly match widgets_values in the workflow JSON.
• Package copies under packages/*/src/**/templates/ are gitignored; regenerate via sync_bundles.py, do not hand-edit.

Decide the operation

Adding a Workflow Template

Step 1 — Obtain the Workflow JSON

• Export from ComfyUI via Save → Export.
• Prefer ComfyUI started with --disable-all-custom-nodes.
• Embedded workflow in image/video: https://comfyui-embedded-workflow-editor.vercel.app/.

Place your_template_name.json in templates/.

Step 2 — Thumbnails

In templates/:

{template_name}-1.webp          # required
{template_name}-2.webp          # optional — compareSlider / hoverDissolve

Prepare as webp (lossy ~65%), reasonable resolution; animated webp for video thumbs before resize.

Step 3 — Entry in templates/index.json

Add the object to the right category's templates array.

Required: name, description, mediaType (image | video | audio | 3d), mediaSubtype (usually webp).

Common optional: title, tags, models, logos, date, openSource, minComfyUIVersion, requiresCustomNodes, thumbnailVariant, tutorialUrl, usage, size, searchRank, io, thumbnail.

{
  "name": "text_to_video_wan",
  "description": "Generate videos from text descriptions.",
  "mediaType": "image",
  "mediaSubtype": "webp",
  "tutorialUrl": "https://comfyanonymous.github.io/ComfyUI_examples/wan/"
}

Step 4 — Bundle

Add the name to the correct array in bundles.json. New media → media-assets-02.

python3 scripts/sync/sync_bundles.py

Step 5 — Embed Model Metadata

For every model-loading node (UNETLoader, VAELoader, CLIPLoader, etc.), add properties.models[]:

Step 6 — Node Versions (Optional)

"properties": {
  "Node name for S&R": "SaveWEBM",
  "cnr_id": "comfy-core",
  "ver": "0.3.26"
}

Step 7 — Sync and Validation

python3 scripts/sync/sync_bundles.py
python3 scripts/validate/validate_templates.py
python3 scripts/validate/validate_thumbnails.py

Step 8 — i18n

sync_data.py does not invent translations. It only applies title / description strings that already exist in scripts/data/i18n.json into templates/index.{locale}.json. Technical fields are copied from English index.json; tags use mappings also stored in i18n.json.

1. Maintain translations in scripts/data/i18n.json under templates.{name} (add or update locale strings). Until a locale string differs from English, that language stays pending / English fallback.

{
  "templates": {
    "your_template_name": {
      "title": {
        "en": "Your Template Title",
        "zh": "您的模板标题",
        "ja": "テンプレートのタイトル"
      },
      "description": {
        "en": "Your template description",
        "zh": "您的模板描述",
        "ja": "テンプレートの説明"
      }
    }
  }
}

2. Then run sync so locale index files pick up the new/updated strings:

python3 scripts/sync/sync_data.py --templates-dir templates

Order matters: edit i18n.json first, then sync. Re-run sync after any later translation edits. For coverage checks and broader i18n work, use /managing-translations.

Step 9 — Version (release PRs only)

See scripts/docs/frozen_bundles.md.

Full release knowledge (label flow, publish pipeline, quota gates, force publish): use /managing-releases.

Renaming a Template

Rename the template slug (name / filenames), not just the display title.

Example: audio_sync_so_lip_sync_video → api_sync_so_lip_sync_video.

Step 1 — Discover every reference

rg -l --glob '!**/node_modules/**' --glob '!**/.git/**' 'OLD_NAME'
# also list assets
ls templates/OLD_NAME* thumbnail/OLD_NAME* output/OLD_NAME* 2>/dev/null

Typical touch points:

Do not bulk-replace inside unrelated binary files. Prefer an explicit file list over a repo-wide rg \| perl loop (large trees can hang).