Release Process & Changelog

Relevant source files

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

• CHANGELOG.md
• README.md
• package.json
• tsconfig.json
• vitest.config.ts

The release process for @cellarnode/beverage-utils is a structured workflow designed to ensure code quality, type safety, and automated distribution of beverage classification utilities. It encompasses a rigorous development cycle—including testing, type checking, and export validation—culminating in an automated GitHub Actions deployment to the npm registry.

The changelog serves as the historical record of this process, documenting version transitions from the initial release through the addition of framework-specific adapters for React, Vue, and Angular, and modernization of the build system for ESM compliance.
Sources: README.md:144-150, CHANGELOG.md:3-37

Development & Build Lifecycle

Before a release is triggered, the codebase must pass through several validation stages defined in the project configuration. The build process utilizes the TypeScript compiler (tsc) to transform source files into a dist/ directory, which contains the compiled JavaScript, type declarations, and source maps.

Pre-release Validation Steps

The following table outlines the scripts required to validate the package before publishing:

Script	Command	Purpose
build	tsc	Compiles TypeScript to JS and generates declarations in dist/.
typecheck	tsc --noEmit	Validates TypeScript types without producing output files.
test	vitest run	Executes the test suite using Vitest.
check-exports	npx publint && npx @arethetypeswrong/cli --pack .	Verifies package exports and ESM/CJS compatibility.
prepublishOnly	npm run build	Ensures the latest build exists before publishing.

Sources: package.json:43-49, CHANGELOG.md:20-22, vitest.config.ts:3-7

Release Flow Diagram

This diagram illustrates the sequence of events from local development to the final npm publication.

Versioning Strategy

The project follows semantic versioning, as evidenced by the progression from initial release to the current stable iterations. Version 0.3.0 marked a significant architectural shift by introducing framework-specific entry points and switching from GitHub Packages to the public npm registry.

Evolution of Distribution

• 0.1.0: Initial release featuring core utilities like buildLabelMap() and formatBeverageLabel().
• 0.2.0: Introduction of the build step (tsc) to ship compiled JS instead of raw TS files, improving compatibility with tools like Turbopack and Next.js.
• 0.3.0: Major expansion including Vue and Angular adapters, GitHub Actions CI/CD, and strict ESM compliance via .js extensions in imports.
• 0.3.1: Refinement of repository URL casing to ensure successful npm provenance verification.

Sources: CHANGELOG.md:3-37, package.json:2-3

Build Configuration

The project utilizes a modern TypeScript configuration to support strict ESM environments and provide high-quality developer experiences through declaration maps and source maps.

Compiler Settings

Key configurations in tsconfig.json include:

• Target/Module: ES2022 and NodeNext for modern runtime compatibility.
• Strict Mode: Enabled for maximum type safety.
• Declaration Support: declaration and declarationMap are enabled to allow consumers to navigate to source code.
• Module Syntax: verbatimModuleSyntax: true is used to enforce precise import/export behavior.

Sources: tsconfig.json:3-14, CHANGELOG.md:15-18

Automated Publishing

The automation system is configured to trigger on pushes to the main branch specifically when a version change is detected.

Summary

The @cellarnode/beverage-utils release process ensures that all updates are thoroughly vetted through automated testing and export validation. By moving to a compiled distribution model and utilizing GitHub Actions for publishing, the project maintains high reliability and compatibility across various JavaScript ecosystems.