Comfy-Org / Comfy-Org/ComfyUI_frontend
[Refactor] Implement multiple entry points to replace single barrel export
- 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
Assessment
This issue has not been assessed yet.