Peer Dependencies Strategy
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The @cellarnode/beverage-utils project employs a modular architecture designed to support multiple JavaScript frameworks while maintaining a zero-dependency core. The strategy relies on optional peer dependencies, allowing the core utilities to remain lightweight for vanilla TypeScript/JavaScript environments while providing deep integration for React, Vue, and Angular via specific entry points.
By using peerDependencies combined with peerDependenciesMeta, the project ensures that users only install the dependencies required for their specific framework adapter. This approach prevents "dependency bloat" and ensures compatibility across different versions of the major frontend frameworks.
Sources: README.md:10-18, package.json:48-75
Modular Entry Points
The library is structured into distinct entry points, each targeting a specific environment or framework. This separation is critical to the peer dependency strategy, as it ensures that framework-specific code (which imports peer dependencies) is never executed or required by users of the core utilities.
Entry Point Configuration
The package.json defines explicit exports for each supported framework, mapping them to specific distribution files.
| Export Path | Intended Use | External Requirements |
|---|---|---|
. | Core utilities (Pure TS) | None |
./react | React Hooks & Query options | react, @tanstack/react-query |
./vue | Vue Composables & Query options | vue, @tanstack/vue-query |
./angular | Angular Services & Query options | @angular/core, @tanstack/angular-query-experimental |
Sources: package.json:18-34, README.md:12-18
Dependency Classification
The project distinguishes between three types of dependencies to manage its footprint and framework compatibility.
1. Core Dependencies
The library has only one hard dependency: i18n-iso-countries. This is required for the normalization and country code resolution logic used in the core utility functions.
Sources: package.json:84-86
2. Optional Peer Dependencies
Framework-specific packages are listed as peer dependencies. Crucially, they are marked as optional using peerDependenciesMeta, which instructs package managers not to warn if these packages are missing, unless the user attempts to use the associated framework entry point.
This diagram shows the relationship between the core package and its optional framework-specific peer dependencies.
Sources: package.json:48-75
3. Development Dependencies
For internal development and testing of all adapters, the project maintains a full suite of framework libraries in devDependencies. This allows for comprehensive type-checking and unit testing across React, Vue, and Angular contexts.
Sources: package.json:76-83
Framework Integration Logic
Each framework adapter follows a consistent pattern: providing a queryOptions factory and a framework-specific hook or service. These modules import from both the core library and the peer dependencies.
Common Adapter Pattern
The following logic is replicated across all adapters, utilizing TanStack Query for data fetching and caching.
- Data Fetching: Uses the global
fetchAPI. - Caching: Sets
staleTime: Infinityas beverage classifications change rarely. - Transformation: Calls the core
buildLabelMaputility to transform API responses.
Sources: src/react/use-beverage-label-map.ts:7-22, src/vue/use-beverage-label-map.ts:7-22, src/angular/beverage-label-map.service.ts:7-22
Dependency Flow for Adapters
This diagram illustrates how framework adapters bridge the gap between the core logic and the framework-specific peer dependencies.
Sources: src/react/use-beverage-label-map.ts:24-26, src/vue/use-beverage-label-map.ts:24-26, src/angular/beverage-label-map.service.ts:24-26
Versioning and Compatibility
The strategy supports multiple major versions of peer dependencies to maximize compatibility. For example, the project supports React 18 and 19, and Angular 17, 18, and 19.
| Peer Dependency | Supported Versions |
|---|---|
react | ^18.0.0 || ^19.0.0 |
vue | ^3.3.0 |
@angular/core | ^17.0.0 || ^18.0.0 || ^19.0.0 |
| TanStack Query (All) | ^5.0.0 |
Sources: package.json:49-54
Summary
The Peer Dependencies Strategy in beverage-utils ensures the library remains a "good citizen" in the JavaScript ecosystem. By isolating framework-specific code into dedicated entry points and utilizing optional peer dependencies, the project provides a lightweight, zero-config experience for vanilla environments while offering robust, first-class support for React, Vue, and Angular developers.