When to Augment vs Fork Types
You'll learn: How to decide between augmenting existing third-party types or maintaining your own forked type definitions based on long-term maintainability.
The Core Decision
When a third-party library's types are incomplete or incorrect, you face a choice: augment the existing module with your additions, or fork by creating a complete replacement set of types.
Think of it like fixing a neighbor's fence. Augmentation is adding a few new boards to their existing structure—you're extending what's there. Forking is building your own complete fence from scratch because theirs is too broken to patch.
When to Choose Augmentation
Augment when:
- The library's types are mostly correct but missing a few properties or methods
- You need to add framework-specific extensions (like custom Express request properties)
- The library is actively maintained and types will likely improve
- Your changes are small, localized additions
- You want automatic updates when the library's types improve
Augmentation keeps you connected to upstream improvements. When the library maintainers fix bugs or add new types, you get those benefits automatically.
When to Fork Types
Fork your own definitions when:
- The library's types are fundamentally wrong or outdated
- The library is unmaintained and types won't improve
- You need to make sweeping changes across many interfaces
- The official types conflict with your use case
- You're wrapping the library with your own abstraction layer
Forking gives you complete control but creates maintenance burden. You own every type definition and must manually track library updates.
The Maintainability Trade-off
Augmentation has low initial cost but depends on external quality. Forking has high initial cost but gives you independence. Choose based on how much the library will change and whether you trust its type maintenance.
Key Takeaway: Augment for small fixes to well-maintained libraries; fork only when types are fundamentally broken or you need full control over a stable API surface.