Package Exports Validation

Relevant source files

The following files were used as context for generating this wiki page:

• package.json
• CHANGELOG.md
• tsconfig.json
• README.md
• src/index.ts

Package Exports Validation in the @cellarnode/beverage-utils project ensures that the library correctly exposes its core utilities and framework-specific adapters (React, Vue, and Angular) to consumers while maintaining compatibility across different module systems and build tools. This system relies on a combination of package.json export maps, TypeScript configuration, and automated linting tools to verify the integrity of the published package.

Sources: package.json:16-36, README.md:12-20, CHANGELOG.md:14-25

Module Entry Points

The project utilizes a multi-entry point architecture defined in the package.json exports field. This allows consumers to import only the specific logic they need, reducing bundle size by avoiding unnecessary framework dependencies.

Defined Export Map

Import Path	Target File (Types)	Target File (Runtime)	Purpose
@cellarnode/beverage-utils	./dist/index.d.ts	./dist/index.js	Core TS utilities, zero dependencies.
@cellarnode/beverage-utils/react	./dist/react/index.d.ts	./dist/react/index.js	React hooks and TanStack Query options.
@cellarnode/beverage-utils/vue	./dist/vue/index.d.ts	./dist/vue/index.js	Vue composables and TanStack Query options.
@cellarnode/beverage-utils/angular	./dist/angular/index.d.ts	./dist/angular/index.js	Angular inject functions and Query options.

Sources: package.json:16-36, README.md:12-20

Build and Distribution Flow

The validation process is integrated into the build pipeline. Source files in the src/ directory are compiled into the dist/ directory via the TypeScript compiler (tsc). Only the dist directory is included in the final NPM package.

The diagram above illustrates the transformation from source code to the distributed package and where validation tools intercept the process.
Sources: package.json:37-38, package.json:44-46, tsconfig.json:15-16

Validation Tooling and Scripts

To maintain strict ESM compliance and prevent "Missing module type" errors in modern bundlers like Turbopack or Next.js, the project employs specific validation scripts.

Automated Checks

The project includes a check-exports script that runs two primary validation tools:

1. publint: Verifies that the exports map in package.json follows NPM best practices and is compatible with various environments.
2. @arethetypeswrong/cli: Checks the package for common TypeScript declaration issues, such as missing types for specific entry points or incorrect module resolution.

"check-exports": "npx publint && npx @arethetypeswrong/cli --pack ."

Sources: package.json:46, CHANGELOG.md:20-25

Compilation Requirements

The tsconfig.json is configured with NodeNext for both module and moduleResolution to ensure strict compatibility with the Node.js ESM loader. This requires relative imports within the source code to include .js extensions, even when referencing .ts files.

Sources: tsconfig.json:4-5, CHANGELOG.md:18-19

Peer Dependency Validation

Framework-specific exports are protected by optional peer dependencies. This ensures that the core library remains lightweight while providing rich integrations for specific ecosystems.

Dependency	Optional	Usage
react	Yes	Required for @cellarnode/beverage-utils/react
vue	Yes	Required for @cellarnode/beverage-utils/vue
@angular/core	Yes	Required for @cellarnode/beverage-utils/angular
@tanstack/*-query	Yes	Required for framework-specific label map fetching

Sources: package.json:49-74, README.md:12-20

Implementation Details

The core entry point (src/index.ts) acts as a central hub for all pure TypeScript logic, which is then re-exported through the main package path.

export type { BeverageSubtype, BeverageCategory, BeverageClassification } from "./types.js";
export type { LabelMap } from "./label-map.js";
export { buildLabelMap } from "./label-map.js";
export { formatBeverageLabel, formatBeverageType } from "./format.js";
export { normalizeToken, resolveCountryCode, parseVolumeToLiters } from "./normalize.js";

Sources: src/index.ts:1-5

Summary of Export Evolution

As of version 0.2.0 and later, the project shifted from exporting raw TypeScript files to exporting compiled JavaScript and declarations from the dist/ directory. This change was specifically implemented to ensure compatibility with modern web frameworks and bundlers.

Sources: CHANGELOG.md:21-25