# Add a Custom Node

Custom nodes add new functionality to ComfyUI (e.g. VideoHelperSuite, LTXVideo, TrentNodes, etc.).

## Overview

Custom nodes are defined in `server/comfy.py` in the `CUSTOM_NODES` list. Each entry is a `[git_url, commit_hash]` pair.

After editing, deploy with `make deploy`. On next runner start, the repo is cloned to `/data/.fal/repos/global_custom_nodes/<name>-<hash>` and symlinked into the ComfyUI custom_nodes folder.

## Step 1 — Find the GitHub repo

For a custom node like `ComfyUI-VideoHelperSuite`, find its GitHub URL:
```
https://github.com/Kosinkadink/ComfyUI-VideoHelperSuite
```

## Step 2 — Pin a commit hash (very important)

**Always pin a specific commit**, never use a branch name. If you use `main`, the behavior changes when the author pushes new commits — things can break without you touching anything.

Get the latest commit hash:
```bash
curl -s "https://api.github.com/repos/Kosinkadink/ComfyUI-VideoHelperSuite/commits?per_page=1" | python3 -c "import sys,json; print(json.load(sys.stdin)[0]['sha'])"
```

Or visit the GitHub repo, click any commit, copy the 40-char SHA.

> **Watch out:** avoid pinning commits that are **too recent** (< 1 day old) — fal's shallow clone may fail to find them. Wait 1–2 days or use a slightly older tagged release.

## Step 3 — Add it to `CUSTOM_NODES`

Open `server/comfy.py` and add your line:

```python
CUSTOM_NODES = [
    # existing nodes...
    ["https://github.com/Kosinkadink/ComfyUI-VideoHelperSuite.git", "2984ec4c4b93292421888f38db74a5e8802a8ff8"],
]
```

## Step 4 — Add Python dependencies

Most custom nodes require extra Python packages. Check the node's `requirements.txt` on GitHub:

```
https://github.com/Kosinkadink/ComfyUI-VideoHelperSuite/blob/<commit>/requirements.txt
```

Add the missing packages to `server/requirements.txt`:

```
# your-custom-node deps
decord==0.6.0
imageio-ffmpeg
```

> **Tip:** pin versions exactly (`==`) to avoid future conflicts.

## Step 5 — Deploy

```bash
cd server
make deploy
```

## Step 6 — Watch the runner logs

Go to https://fal.ai/dashboard/apps/<org>/<app>/runners and click the active/starting runner. Watch for:

✅ `[CustomNodeName] Loaded X nodes`
❌ `ImportError: No module named 'xxx'` → add that module to `requirements.txt`
❌ `Failed to clone repository` → commit hash too recent, use an older one
❌ Node-specific errors → check the custom node's GitHub issues

## Step 7 — Test

Relaunch the frontend (`./run.sh`) and check your workflow. The new nodes should appear in the node menu.

## Troubleshooting

- **Node shows "UNKNOWN" in the UI**: the node crashed on import. Check runner logs.
- **`causal_fix` / unexpected keyword argument**: custom node requires a newer/older ComfyUI version than what you're using.
- **Red border on node**: model file referenced by the node doesn't exist. Check `ADD_MODELS.md`.
- **Custom node disabled**: the wheel patch logs a warning instead of crashing. One broken node won't kill the server.

## Example — adding TrentNodes (already in the config)

```python
CUSTOM_NODES = [
    ["https://github.com/TrentHunter82/TrentNodes.git", "05a4dc0d4a19224623256b0c9825b5fc975c187a"],
]
```

TrentNodes requires these deps (already in `requirements.txt`):
```
bitsandbytes==0.49.2
llama-cpp-agent==0.0.17
# MiniCPM patch applied at runtime in server.py
```
