CI/CD and GitHub Actions

Relevant source files

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

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

The beverage-utils project employs a structured Continuous Integration and Continuous Deployment (CI/CD) pipeline powered by GitHub Actions. This system automates the validation, building, and distribution of the library to ensure high code quality and reliable releases to the npm registry. The pipeline is designed to support a multi-framework architecture, validating the core TypeScript logic as well as adapters for React, Vue, and Angular.

The CI/CD infrastructure focuses on four primary pillars: static analysis (typechecking and linting), automated testing, build verification, and automated publishing with provenance. These processes ensure that every contribution meets the project's standards before being merged or released.
Sources: CHANGELOG.md:14-15, README.md:183-193

Continuous Integration (CI) Workflow

The CI workflow is triggered on various events to validate code changes. It encompasses a suite of checks that must pass to maintain the integrity of the main branch.

Validation Suite

The project utilizes several scripts defined in package.json to perform comprehensive validation:

Task	Command	Description
Typecheck	npm run typecheck	Validates TypeScript integrity without emitting files using tsc --noEmit.
Test	npm run test	Executes the unit test suite using Vitest.
Build	npm run build	Compiles the TypeScript source code into the dist/ directory.
Linting	npm run check-exports	Uses publint and @arethetypeswrong/cli to verify ESM compatibility and export validity.

Sources: package.json:44-49, CHANGELOG.md:14-15

Build and Compilation Logic

The build process is governed by the tsconfig.json configuration, which targets ES2022 and uses NodeNext module resolution. The CI system ensures that the project can successfully compile into a strict ESM-compliant package, including source maps and declaration maps for downstream debugging.
Sources: tsconfig.json:3-15, CHANGELOG.md:21-22

The diagram above illustrates the sequential validation steps performed during the CI process to ensure package integrity.
Sources: package.json:44-49, CHANGELOG.md:14-15

Release and Deployment (CD) Workflow

The deployment pipeline is strictly tied to the versioning of the package. The project has transitioned from GitHub Packages to the public npm registry for its distribution.

Automated Publishing

The auto-publish workflow is triggered when a push to the main branch is detected and the version field in package.json has been updated. This process includes:

1. Pre-publish Verification: The prepublishOnly script automatically runs the build command to ensure the dist/ folder is populated with the latest compiled JS and type declarations.
2. npm Provenance: The workflow publishes to npm with provenance, providing a verifiable link between the published package and the source GitHub repository.
3. Registry Configuration: The package is configured for public access via the publishConfig setting.

Sources: package.json:13-15, package.json:45, CHANGELOG.md:16, README.md:193

Release Flow Diagram

The following sequence diagram demonstrates the relationship between the developer actions and the automated deployment system.

This diagram outlines the automated steps from the moment a developer pushes a version change to the final availability on npm.
Sources: package.json:45, README.md:189-193, CHANGELOG.md:16-17

Development Environment and Tooling

To maintain consistency between local development and the CI/CD environment, the project mandates specific engine requirements and provides standardized scripts.

• Node.js Requirement: The environment requires Node.js version >=20.19.0.
• Test Runner: Vitest is used for execution, with configuration defined in vitest.config.ts.
• Dependency Management: Contributions are expected to be tested locally using npm test and npm run typecheck before pushing to the repository.

Sources: package.json:71-73, vitest.config.ts:3-7, README.md:183-187

Export Integrity

A critical part of the CI process is the check-exports script. This ensures that the multi-entry point architecture (Core, React, Vue, Angular) is correctly mapped in package.json and that the compiled files in dist/ are accessible to consumers without "Missing module type" or resolution errors.
Sources: package.json:16-35, package.json:46, CHANGELOG.md:24

Summary

The CI/CD pipeline for beverage-utils provides a robust automated framework for maintaining the library. By integrating strict TypeScript validation, framework-specific adapter testing via Vitest, and an automated release process with npm provenance, the project ensures that every version published is both technically sound and securely delivered.