Adding Deprecation Warnings
Developmentadding-deprecation-warningsAdding Deprecation Warnings is an Agent Skill for development published in the Comfy-Org/ComfyUI_frontend repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Adds deprecation warnings for renamed or removed properties/APIs. Searches custom node ecosystem for usage, applies defineDeprecatedProperty helper, adds JSDoc. Triggers on: deprecate, deprecation warning, rename property, backward compatibility.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/Comfy-Org/ComfyUI_frontend/blob/HEAD/.claude/skills/adding-deprecation-warnings/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/adding-deprecation-warnings, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Adding Deprecation Warnings
Adds backward-compatible deprecation warnings for renamed or removed
properties using the defineDeprecatedProperty helper in
src/lib/litegraph/src/utils/feedback.ts.
When to Use
- A property or API has been renamed and custom nodes still use the old name
- A property is being removed but needs a grace period
- Backward compatibility must be preserved while nudging adoption
Steps
1. Search the Custom Node Ecosystem
Before implementing, assess impact by searching for usage of the deprecated property across ComfyUI custom nodes:
Use the comfy_codesearch tool to search for the old property name.
Search for both `widget.oldProp` and just `oldProp` to catch all patterns.
Document the usage patterns found (property access, truthiness checks, caching to local vars, style mutation, etc.) — these all must continue working.
2. Apply the Deprecation
Use defineDeprecatedProperty from src/lib/litegraph/src/utils/feedback.ts:
import { defineDeprecatedProperty } from '@/lib/litegraph/src/utils/feedback'
/** @deprecated Use {@link obj.newProp} instead. */
defineDeprecatedProperty(
obj,
'oldProp',
'newProp',
'obj.oldProp is deprecated. Use obj.newProp instead.'
)
3. Checklist
- Ecosystem search completed — all usage patterns are compatible
-
defineDeprecatedPropertycall added after the new property is assigned - JSDoc
@deprecatedtag added above the call for IDE support - Warning message names both old and new property clearly
-
pnpm typecheckpasses -
pnpm lintpasses
4. PR Comment
Add a PR comment summarizing the ecosystem search results: which repos use the deprecated property, what access patterns were found, and confirmation that all patterns are compatible with the ODP getter/setter.
How defineDeprecatedProperty Works
- Creates an
Object.definePropertygetter/setter on the target object - Getter returns
this[currentKey], setter assignsthis[currentKey] - Both log via
warnDeprecated, which deduplicates (once per unique message per session via aSet) enumerable: falsekeeps the alias out ofObject.keys()/for...in/JSON.stringifyconfigurable: trueallows further redefinition if needed
Edge Cases
- Truthiness checks (
if (widget.oldProp)) — works, getter fires - Caching to local var (
const el = widget.oldProp) — works, warns once then the cached ref is used directly - Style/property mutation (
widget.oldProp.style.color = 'red') — works, getter returns the real object - Serialization (
JSON.stringify) —enumerable: falseexcludes it - Heavy access in loops —
warnDeprecateddeduplicates, only warns once per session regardless of call count