Imported from yolain/ComfyUI-Easy-Media (
AGENTS.md). Install upstream withnpx skills add yolain/ComfyUI-Easy-Media. Copyright stays with the author.
ComfyUI Easy Media
Tech Stack
- Backend: Python, using comfyui-nodes-** skills to develop.
- Frontend: React v19, shadcn/ui + Tailwind CSS v4 for components, Lucide for icons, Bun for package manager and build, Vitest for testing.
Build, Test, and Development Commands
Adding shadcn/ui components
# From repo root
bunx shadcn add <component-name>
Build
# Dev build (unminified, outputs to dist/dev) — use during normal development
bun run dev # watch mode with hot reload → dist/dev
bun run build # one-shot dev build → dist/dev
# Release build (minified, outputs to dist/release) — REQUIRED before git commit
bun run build:release # production build → dist/release
Skill Synchronization
- Keep Codex skills in sync — When changing any skill in this project, overwrite the corresponding Codex skill with the updated project version so both copies remain identical
Code Style
Backend
- Reuse utils first — Before writing new code, check
utils/for existing utility functions; if none exists, add it there instead of duplicating code - File naming —
kebab_case.pyfor nodes、utils、modules;PascalCase.pyfor classes - Type hints — Use type hints for all public methods and function parameters
- Error handling — Use
try/exceptto explicitly catch exceptions; never swallow exceptions silently
Frontend
- TypeScript first — strict mode, no
anywithout reason - File naming —
PascalCase.tsxfor components,camelCasefor dir,kebab-case.tsfor modules - Import aliases — use
@/*forsrc/paths - React components — functional only, hooks-based
- Reusable hooks — When component logic has reusable state/effect behavior, write it directly in
src/hooksand call it from components instead of duplicating the logic inline - Test location — Write test cases separately under
src/tests; do not colocate test files with components or other source modules - Never use raw HTML elements for interactive controls — use shadcn/ui equivalents (
<Button>not<button>,<Input>not<input>,<Textarea>not<textarea>,<Select>not<select>). Exception:src/components/ui/**(the shadcn/ui primitives themselves may use raw elements) - Error handling — always handle errors explicitly; never swallow exceptions silently
- Color tokens only — All colors are defined as CSS custom properties in
src/styles/global.cssand mapped to Tailwind utilities via@theme inline; use theme tokens instead of hardcoded values - No raw Tailwind colors — Do not use raw color utilities such as
text-zinc-*,border-slate-*,bg-[#...], ortext-[#...]; use classes likebg-background,border-border,text-foreground, andtext-muted-foreground - Color exceptions —
bg-whiteandbg-blackare allowed for canvas/node editor backgrounds when explicit backgrounds are intentional - Adding colors — Add new colors as CSS custom property tokens in
src/styles/index.cssunder@theme inline, then consume them through Tailwind utilities
Sampling Preview Regression Guards
- Tiny VAE preview decoders may return either normalized float pixels (
0..1) oruint8pixels (0..255). When interpolatinguint8preview frames, preserve that scale and cast the result back touint8before generic float conversion. Passing interpolated0..255floats through a0..1clamp saturates the preview to white. - Keep
tests/test_sampling_preview.py::test_decode_preview_frames_resamples_uint8_without_clipping_to_whiteas a regression test for the white-preview failure. - The sampling preview belongs to the
easy multitrackProjectnode itself. It is not part ofTRACK_DATAorMultiTrackWidget. Keep its DOM widget inside the node layout with bounded min/max height and bounded pointer hit-testing.
Git Workflow
Branch Strategy
- Switch to
mainand ensure it is up to date before creating a new feature branch when the task requires branch work - If a matching feature branch already exists, use it instead of creating a duplicate
- For code changes, create feature branches from
main; documentation-only or assistant-rules changes do not require a new branch unless requested - When fixing code from an issue, create a branch specifically for that issue
- Before switching or committing, check whether the current branch is behind
mainwith conflicting changes; rebasemaininto the current branch if needed
Commit Rules
- Group commits by feature or responsibility, not only by file type
- Keep
dist/changes separate from feature/source commits when frontend builds update generated output - Use
git diffto inspect changes and decide logical commit grouping before committing - Use conventional commit messages:
<type>: <description>
<optional body>
- Allowed commit types:
feat,fix,refactor,docs,test,chore,perf,ci
Pull Request Workflow
- After pushing a branch to remote, create a corresponding PR when requested or when completing branch-based work
- If a similar PR is already open, ask whether to contribute to that PR instead
- When creating PRs, analyze the full branch history, not only the latest commit
- Use
git diff [base-branch]...HEADto review the full change set - Include a concise PR summary and a test plan
- Push with
-uwhen publishing a new branch
Pre-Push Review
- Run applicable reviews before pushing substantial code changes:
- Frontend changes: React/TypeScript review
- Backend changes: Python/ComfyUI node review
- Localization changes: i18n review
- Address review findings and re-run review after major changes
