ComfyUI_frontend/frontend-v3-compatibility-summary.md

ComfyUI Frontend V3 Compatibility - Implementation Summary

Core Concept

Import-based API versioning with proxy-synchronized data layers. Extensions choose their API version through imports, getting typed interfaces and guaranteed backward compatibility.

Architecture Overview

1. Version-Specific Imports

// Legacy (unchanged)
import { app } from '@/scripts/app'

// Version-specific
import { app } from '@/scripts/app/v1'       // v1.x API
import { app } from '@/scripts/app/v1_2'     // v1.2 API
import { app } from '@/scripts/app/v3'       // v3.x API
import { app } from '@/scripts/app/latest'   // Latest

// Typed interfaces per version
app.registerExtension({
  beforeRegisterNodeDef(nodeType, nodeData: ComfyNodeDefV1_2, app: ComfyAppV1_2) {
    // nodeData guaranteed to be v1.2 format
  }
})

2. Dual Endpoint Data Fetching

// Simultaneous fetching from multiple endpoints
const [currentData, v3Data] = await Promise.allSettled([
  api.get('/object_info'),      // Current format
  api.get('/v3/object_info')    // V3 format
])

// All versions stored and transformed
nodeDefinitions.value = {
  canonical: mergeToCanonical(currentData, v3Data),
  v1: transformToV1(currentData),
  v1_2: transformToV1_2(currentData),
  v3: v3Data || transformToV3(currentData)
}

3. Proxy-Based Synchronization

// Bidirectional data sync through proxies
const createV1_2Proxy = (canonical: ComfyNodeDefLatest) => {
  return new Proxy({}, {
    get(target, prop) {
      return transformCanonicalToV1_2(canonical, prop)
    },
    set(target, prop, value) {
      transformV1_2ToCanonical(canonical, prop, value)
      notifyChange(canonical.name, prop, value)
      return true
    }
  })
}

Implementation Structure

Phase 1: API Infrastructure (3-4 days)

• Entry Points: src/scripts/app/v1.ts, src/scripts/app/v1_2.ts, etc.
• Type Definitions: src/types/versions/ with version-specific interfaces
• Adapters: src/scripts/app/adapters/ for API compatibility layers

Phase 2: Data Layer (2-3 days)

• Multi-Version Store: Single store with all format versions
• Transform Pipeline: src/utils/versionTransforms.ts for format conversion
• Reactive Getters: Version-specific computed properties

Phase 3: Proxy System (2-3 days)

• Bidirectional Proxies: src/utils/versionProxies.ts
• Change Notification: Event system for data sync
• Type Safety: Proper typing for proxy objects

Phase 4: Extension Integration (2-3 days)

• Version-Aware Service: Extensions grouped by API version
• Hook Invocation: Transform args per version before calling
• App Adapters: Version-specific app instances

Key Benefits

• Type Safety: Compile-time checking for each API version
• Zero Breaking Changes: Existing extensions work unchanged
• Bidirectional Sync: Changes through any API stay synchronized
• Performance: No runtime version detection overhead
• Future Proof: Easy to add new API versions
• Developer Experience: Clear, typed interfaces

Migration Path

// Step 1: No changes (works with latest)
import { app } from '@/scripts/app'

// Step 2: Explicit version (better compatibility)  
import { app } from '@/scripts/app/v1_2'

// Step 3: Use newer APIs when ready
import { app } from '@/scripts/app/latest'

Example Usage

// v1.2 Extension
import { app } from '@/scripts/app/v1_2'

app.registerExtension({
  name: 'MyExtension',
  beforeRegisterNodeDef(nodeType, nodeData: ComfyNodeDefV1_2, app) {
    // nodeData.input.required - v1 format
    // nodeData.inputs - v1.2 format
    if (nodeData.inputs) {
      // Use v1.2 features
    } else {
      // Fallback to v1 format
    }
  }
})

Implementation Timeline

• Phase 1: API Version Infrastructure (3-4 days)
• Phase 2: Multi-Version Data Layer (2-3 days)
• Phase 3: Proxy-Based Synchronization (2-3 days)
• Phase 4: Extension System Integration (2-3 days)
• Phase 5: Migration Tools & Documentation (1-2 days)

Total: 10-15 days

This approach provides type-safe API versioning that scales with ComfyUI's growth while maintaining complete backward compatibility and smooth migration paths for extension developers.