Comfy-Org / Comfy-Org/ComfyUI_frontend

[Refactor] Implement multiple entry points to replace single barrel export

Open
#4,698 1 comment 1 reaction 1 assignee Claimed by @christian-byrne View on GitHub
area:litegraph developer experience
Dominant language
TypeScript
Stars
2k
Forks
699
Avg merge
1d 7h
Merged PRs (30d)
490

Description

## Overview

The current litegraph.js uses a single barrel export pattern with 170+ exports from `src/litegraph.ts`. This creates several issues:
- Large bundle sizes when tree-shaking fails
- Slow TypeScript compilation
- Circular dependency risks
- Difficult API discovery

## Proposed Solution

Implement multiple entry points following modern library patterns:

```typescript
// Current approach (single barrel)
import { LGraph, LGraphCanvas, LGraphNode, BaseWidget } from '@comfyorg/litegraph'

// Proposed approach (multiple entry points)
import { LGraph } from '@comfyorg/litegraph/core'
import { LGraphCanvas } from '@comfyorg/litegraph/canvas'
import { BaseWidget, NumberWidget } from '@comfyorg/litegraph/widgets'
import { Subgraph, SubgraphNode } from '@comfyorg/litegraph/subgraph'
```

## Benefits

1. **Better tree-shaking** - Bundlers can eliminate entire unused modules
2. **Faster builds** - Only parse/compile imported modules
3. **Clearer dependencies** - Explicit subsystem dependencies
4. **Reduced memory usage** - TypeScript LSP loads less code
5. **Parallel loading** - Modern bundlers can load entries in parallel

## Implementation Plan

### Phase 1: Non-Breaking Addition
Add new entry points alongside existing barrel:

```json
{
"exports": {
".": "./dist/litegraph.js", // Keep existing
"./core": "./dist/core/index.js", // Add new
"./canvas": "./dist/canvas/index.js",
"./widgets": "./dist/widgets/index.js",
"./subgraph": "./dist/subgraph/index.js",
"./types": "./dist/types/index.js"
}
}
```

### Phase 2: Migration Period
- Mark barrel exports as deprecated
- Provide migration guide and tooling
- Update documentation

### Phase 3: Breaking Change (v2.0)
- Remove barrel export
- Multiple entry points only

## Proposed Module Structure

```
core/
- LGraph
- LiteGraphGlobal
- LLink
- LGraphNode (base only)

canvas/
- LGraphCanvas
- CanvasPointer
- DragAndScale
- rendering utilities

widgets/
- BaseWidget
- NumberWidget
- SliderWidget
- ComboWidget
- etc.

subgraph/
- Subgraph
- SubgraphNode
- SubgraphInput/Output
- ExecutableNodeDTO

types/
- interfaces
- enums
- type definitions
```

## Tasks

### 1. Analyze Current Export Usage Patterns

Use Sourcegraph (https://cs.comfy.org/search) to audit how exports are currently used:

**Core class imports:**
- `from ['"@comfyorg/litegraph'"] import.*\bLGraph\b` - Find LGraph usage
- `from ['"@comfyorg/litegraph'"] import.*\bLGraphCanvas\b` - Find LGraphCanvas usage
- `from ['"@comfyorg/litegraph'"] import.*\bLGraphNode\b` - Find LGraphNode usage
- `from ['"@comfyorg/litegraph'"] import.*\bLiteGraph\b` - Find singleton usage

**Widget imports:**
- `from ['"@comfyorg/litegraph'"] import.*(BaseWidget < /dev/null | NumberWidget|SliderWidget|ComboWidget|TextWidget|ButtonWidget|BooleanWidget|KnobWidget)` - Find widget usage
- `import.*Widget.*from ['"@comfyorg/litegraph'"]` - Find any widget imports

**Subgraph imports:**
- `from ['"@comfyorg/litegraph'"] import.*(Subgraph|SubgraphNode|SubgraphInput|SubgraphOutput)` - Find subgraph usage
- `patternType:regexp ExecutableNodeDTO|SubgraphIO` - Find DTO usage

**Type imports:**
- `import type.*from ['"@comfyorg/litegraph'"]` - Find type-only imports
- `from ['"@comfyorg/litegraph'"] import type` - Alternative type import syntax
- `INodeSlot|IWidget|Point|Size|Rect|ConnectingLink` - Common type usage

**Namespace imports:**
- `import \* as.*from ['"@comfyorg/litegraph'"]` - Find namespace imports
- `const.*=.*require\(['"@comfyorg/litegraph'"]\)` - Find CommonJS usage

**Destructured imports:**
- `const \{.*\} = .*['"@comfyorg/litegraph'"]` - Find destructured requires
- `from ['"@comfyorg/litegraph'"] import \{[^}]{50,}` - Find large import statements

**Extension patterns:**
- `repo:^github\.com/.*comfy.*extension patternType:regexp from ['"@comfyorg/litegraph'"]` - Extensions using litegraph
- `LiteGraph\.registerNodeType` - Find node registrations
- `extends LGraphNode` - Find custom node classes

### 2. Design Module Boundaries
- Group frequently co-imported items
- Minimize circular dependency potential
- Consider inheritance hierarchies

### 3. Create Build Configuration
- Update vite.config.mts for multiple entries
- Configure TypeScript paths
- Set up proper tree-shaking hints

### 4. Add Compatibility Layer
- Create migration shim that preserves barrel
- Add deprecation warnings
- Generate migration report for codebases

### 5. Update Documentation
- Entry point reference
- Migration guide
- API documentation per module

## Related Issues

- Circular dependency issues with Subgraph system
- Bundle size concerns
- TypeScript performance

## Questions to Resolve

1. How to handle the singleton `LiteGraph` instance?
2. Where do shared utilities go?
3. How to maintain backward compatibility during transition?
4. Impact on extension ecosystem?

## Success Metrics

- [ ] Reduced bundle sizes (measure before/after)
- [ ] Faster TypeScript compilation
- [ ] No increase in circular dependencies
- [ ] Successful migration of ComfyUI frontend

┆Issue is synchronized with this [Notion page](https://www.notion.so/Issue-4698-Refactor-Implement-multiple-entry-points-to-replace-single-barrel-export-2476d73d365081618a8ce90eaca331b7) by [Unito](https://www.unito.io)

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.