ComfyUI_frontend/CONTRIBUTING.md

Contributing to ComfyUI Frontend

We're building this frontend together and would love your help — no matter how you'd like to pitch in! You don't need to write code to make a difference.

Ways to Contribute

• Pull Requests: Add features, fix bugs, or improve code health. Browse issues for inspiration. Look for the Good first issue label if you're new to the project.
• Vote on Features: Give a 👍 to the feature requests you care about to help us prioritize.
• Verify Bugs: Try reproducing reported issues and share your results (even if the bug doesn't occur!).
• Community Support: Hop into our Discord to answer questions or get help.
• Share & Advocate: Tell your friends, tweet about us, or share tips to support the project.

Have another idea? Drop into Discord or open an issue, and let's chat!

Development Setup

Prerequisites & Technology Stack

• Required Software:

  • Node.js (v18 or later to build; v24 for vite dev server) and pnpm
  • Git for version control
  • A running ComfyUI backend instance

• Tech Stack:

  • Vue 3.5 Composition API with TypeScript
  • Pinia for state management
  • PrimeVue with TailwindCSS for UI
  • litegraph.js (integrated in src/lib) for node editor
  • zod for schema validation
  • vue-i18n for internationalization

Initial Setup

1. Clone the repository:

   git clone https://github.com/Comfy-Org/ComfyUI_frontend.git
   cd ComfyUI_frontend
   

2. Install dependencies:

   pnpm install
   

3. Configure environment (optional): Create a .env file in the project root based on the provided .env.example file.

   Note about ports: By default, the dev server expects the ComfyUI backend at localhost:8188. If your ComfyUI instance runs on a different port, update this in your .env file.

Dev Server Configuration

To launch ComfyUI and have it connect to your development server:

python main.py --port 8188

Git pre-commit hooks

Run pnpm prepare to install Git pre-commit hooks. Currently, the pre-commit hook is used to auto-format code on commit.

Dev Server

• Start local ComfyUI backend at localhost:8188
• Run pnpm dev to start the dev server
• Run pnpm dev:electron to start the dev server with electron API mocked

Access dev server on touch devices

Enable remote access to the dev server by setting VITE_REMOTE_DEV in .env to true.

After you start the dev server, you should see following logs:

> comfyui-frontend@1.3.42 dev
> vite


  VITE v5.4.6  ready in 488 ms

  ➜  Local:   http://localhost:5173/
  ➜  Network: http://172.21.80.1:5173/
  ➜  Network: http://192.168.2.20:5173/
  ➜  press h + enter to show help

Make sure your desktop machine and touch device are on the same network. On your touch device, navigate to http://<server_ip>:5173 (e.g. http://192.168.2.20:5173 here), to access the ComfyUI frontend.

⚠️ IMPORTANT: The dev server will NOT load JavaScript extensions from custom nodes. Only core extensions (built into the frontend) will be loaded. This is because the shim system that allows custom node JavaScript to import frontend modules only works in production builds. Python custom nodes still function normally. See Extension Development Guide for details and workarounds. And See Extension Overview for extensions overview.

Development Workflow

Architecture Decision Records

We document significant architectural decisions using ADRs (Architecture Decision Records). See docs/adr/ for all ADRs and the template for creating new ones.

Backporting Changes to Release Branches

When you fix a bug that affects a version in feature freeze, we use an automated backport process to apply the fix to the release candidate branch.

Real Example

• Subgraphs feature was released in v1.24
• While developing v1.25, we discovered a bug in subgraphs
• v1.24 is in feature freeze (only accepting bug fixes, no new features)
• The fix needs to be applied to both main (v1.25) and the v1.24 release candidate

How to Backport Your Fix

1. Create your PR fixing the bug on main branch as usual

2. Before merging, add these labels to your PR:

   • needs-backport - triggers the automated backport workflow
   • 1.24 - targets the core/1.24 release candidate branch

3. Merge your PR normally

4. The automated workflow will:

   • Create a new branch from core/1.24
   • Apply your changes to that branch
   • Open a new PR to core/1.24
   • Comment on your original PR with a link to the backport PR

When to Use Backporting

• Bug fixes for features already released
• Security fixes
• Critical issues affecting existing functionality
• Never for new features (these wait for the next release cycle)

Handling Conflicts

If the automated cherry-pick fails due to conflicts, the workflow will comment on your PR with:

• The list of conflicting files
• Instructions to manually cherry-pick to the release candidate branch

See PR #4616 for the actual subgraph bugfix that was backported from v1.25 to v1.24.

Code Editor Configuration

Recommended Setup

This project includes .vscode/launch.json.default and .vscode/settings.json.default files with recommended launch and workspace settings for editors that use the .vscode directory (e.g., VS Code, Cursor, etc.).

We've also included a list of recommended extensions in .vscode/extensions.json. Your editor should detect this file and show a human friendly list in the Extensions panel, linking each entry to its marketplace page.

MCP Integrations

Playwright Browser Automation

The Playwright MCP server enables LLM coding assistants (like Copilot, Claude Code, etc.) to control and inspect web browsers programmatically. This allows assistants to navigate websites, take screenshots, and interact with web pages on your behalf.

For ComfyUI_frontend development, you can ask coding assistants to use Playwright screenshots to continuously verify that your code changes produce the expected visual results.

Setup for Claude Code

After installing dependencies with pnpm i, the Playwright MCP server will be automatically available when you start Claude Code locally.

Here's how Claude Code can use the Playwright MCP server to inspect the interface of the local development server (assuming you're running the dev server at localhost:5173):

> navigate to localhost:5173 and take a screenshot.
   tell me the items in the menubar

● I'll navigate to localhost:5173 and take a
  screenshot to see the menubar items.

● playwright:playwright_navigate (MCP)(url:       …
                                      "http://local
                                      host:5173")
  ⎿  Navigated to http://localhost:5173

● playwright:playwright_screenshot (MCP)(name: "lo…
                                        alhost_5173
                                        _menubar")

  ⎿ Screenshot saved to: ../../../Downloads/localho
    st_5173_menubar-2025-05-30T17-23-00-942Z.png
  ⎿  Screenshot also stored in memory with name:
     'localhost_5173_menubar'

● Read(../../../Downloads/localhost_5173_menubar-2…
      25-05-30T17-23-00-942Z.png)
  ⎿  Read image (94.3KB)

● Based on the screenshot, I can see the menubar at
   the top of the ComfyUI interface contains the
  following items:

  Main Menubar Items:
  - Workflow - Menu for workflow-related actions
  - Edit - Menu for editing operations
  - Help - Menu for help and documentation

  Additional UI Elements:
  - ComfyUI Logo - On the far left
  - Workflow Tab - Shows "Unsaved Workflow" with a
  dropdown and close button
  - Layout Controls - On the far right (grid view
  and hamburger menu icons)

  The interface shows a typical ComfyUI workflow
  graph with nodes like "Load Checkpoint", "CLIP
  Text Encode (Prompt)", "KSampler", and "Empty
  Latent Image" connected with colored cables.

Testing

Unit Tests

• pnpm i to install all dependencies
• pnpm test:unit to execute all unit tests

Playwright Tests

Playwright tests verify the whole app. See browser_tests/README.md for details.

Running All Tests

Before submitting a PR, ensure all tests pass:

pnpm test:unit
pnpm test:browser
pnpm typecheck
pnpm lint
pnpm format

Code Style Guidelines

TypeScript

• Use TypeScript for all new code
• Avoid any types - use proper type definitions
• Never use @ts-expect-error - fix the underlying type issue

Vue 3 Patterns

• Use Composition API for all components
• Follow Vue 3.5+ patterns (props destructuring is reactive)
• Use <script setup> syntax

Styling

• Use Tailwind CSS classes instead of custom CSS
• Follow the existing dark theme pattern: dark-theme: prefix (not dark:)

Internationalization

• All user-facing strings must use vue-i18n
• Add translations to src/locales/en/main.json
• Use translation keys: const { t } = useI18n(); t('key.path')

Icons

The project supports three types of icons, all with automatic imports (no manual imports needed):

1. PrimeIcons - Built-in PrimeVue icons using CSS classes: <i class="pi pi-plus" />
2. Iconify Icons - 200,000+ icons from various libraries: <i class="icon-[lucide--settings]" />, <i class="icon-[mdi--folder]" />
3. Custom Icons - Your own SVG icons: <i-comfy:workflow />

Icons are powered by the unplugin-icons system, which automatically discovers and imports icons as Vue components. Custom icons are stored in packages/design-system/src/icons/ and processed by packages/design-system/src/iconCollection.ts with automatic validation.

For detailed instructions and code examples, see packages/design-system/src/icons/README.md.

Working with litegraph.js

Since Aug 5, 2025, litegraph.js is now integrated directly into this repository. It was merged using git subtree to preserve the complete commit history (PR #4667, ADR).

Important Notes

• Issue References: Commits from the original litegraph repository may contain issue/PR numbers (e.g., #4667) that refer to issues/PRs in the original litegraph.js repository, not this one.
• File Paths: When viewing historical commits, file paths may show the original structure before the subtree merge. In those cases, just consider the paths relative to the new litegraph folder.
• Contributing: All litegraph modifications should now be made directly in this repository.

The original litegraph repository (https://github.com/Comfy-Org/litegraph.js) is now archived.

Submitting Changes

Pull Request Process

1. Ensure your branch is up to date with main
2. Run all tests and ensure they pass
3. Create a pull request with a clear title and description
4. Use conventional commit format for PR titles:
   • [feat] for new features
   • [fix] for bug fixes
   • [docs] for documentation
   • [refactor] for code refactoring
   • [test] for test additions/changes
   • [chore] for maintenance tasks

PR Description Template

## Description
Brief description of the changes

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update

## Testing
- [ ] Unit tests pass
- [ ] Component tests pass
- [ ] Browser tests pass (if applicable)
- [ ] Manual testing completed

## Screenshots (if applicable)
Add screenshots for UI changes

Review Process

1. All PRs require at least one review
2. Address review feedback promptly
3. Keep PRs focused - one feature/fix per PR
4. Large features should be discussed in an issue first

Questions?

If you have questions about contributing:

• Check existing issues and discussions
• Ask in our Discord
• Open a new issue for clarification

Thank you for contributing to ComfyUI Frontend!