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-01 — 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, requiresCustomNodes, thumbnailVariant, tutorialUrl, usage, size, vram, 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-01.

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.

---

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).

Step 2 — Rename assets with git mv

git mv templates/OLD_NAME.json templates/NEW_NAME.json
git mv templates/OLD_NAME-1.webp templates/NEW_NAME-1.webp
# if present:
git mv templates/OLD_NAME-2.webp templates/NEW_NAME-2.webp
git mv thumbnail/OLD_NAME_thumbnail.mp4 thumbnail/NEW_NAME_thumbnail.mp4
git mv output/OLD_NAME.mp4 output/NEW_NAME.mp4

Adjust extensions to match what exists (.webp, .mp4, etc.).

Step 3 — Update text references

Replace OLD_NAME → NEW_NAME in every text/JSON file from Step 1, especially:

• "name": "OLD_NAME"
• bundles.json entry
• io.outputs[].file (e.g. OLD_NAME.mp4)
• thumbnail: ["thumbnail/OLD_NAME_..."]
• i18n object keys

Use a targeted replace on the known file list (not a whole-repo scan that touches binaries).

Step 4 — Sync packages

python3 scripts/sync/sync_bundles.py

Confirms manifest.json ids/filenames point at NEW_NAME, and regenerates gitignored package template copies.

Step 5 — i18n / MCP if needed

• Rename the template key inside scripts/data/i18n.json (templates.OLD_NAME → templates.NEW_NAME, and any pending-tracking entries). Sync will not move those keys for you.
• After the i18n key rename (and any translation string updates), run:

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

• If locale files still contain OLD_NAME in name / media paths, finish those replaces before or after sync as needed.
• If the template exists in templates/index.mcp.json, update it (or follow /managing-mcp-index).

Step 6 — Verify

rg -l --glob '!**/node_modules/**' --glob '!**/.git/**' 'OLD_NAME' || echo '(none)'
ls templates/NEW_NAME.json templates/NEW_NAME-1.webp
python3 scripts/validate/validate_templates.py
python3 scripts/validate/validate_thumbnails.py

No remaining OLD_NAME refs should remain (except unrelated historical docs). Bundle membership stays the same unless the user also asks to move bundles (/managing-bundles).

Rename caveats

• Renaming the slug is a breaking change for anything that pins the old template id (Comfy Cloud, docs links, MCP callers). Mention that if relevant.
• Do not bump pyproject.toml for a rename-only PR unless it is an intentional release.
• Display-only title/description edits are not a rename; edit index.json / i18n only.

---

Validation (shared)

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

---

Common User Requests

---

File Quick-Reference