| name | adding-deprecation-warnings |
| description | 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. |
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'
defineDeprecatedProperty(
obj,
'oldProp',
'newProp',
'obj.oldProp is deprecated. Use obj.newProp instead.'
)
3. Checklist
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.defineProperty getter/setter on the target object
- Getter returns
this[currentKey], setter assigns this[currentKey]
- Both log via
warnDeprecated, which deduplicates (once per unique
message per session via a Set)
enumerable: false keeps the alias out of Object.keys() / for...in
/ JSON.stringifyconfigurable: true allows 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: false excludes it
- Heavy access in loops —
warnDeprecated deduplicates, only warns
once per session regardless of call count
