NPM Publishing and Provenance

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 @cellarnode/beverage-utils project implements a modern, automated release pipeline for publishing to the npm registry. This system ensures high package quality through rigorous validation and provides security through npm provenance, which allows consumers to verify that the package was built and published from a specific GitHub Actions workflow.

The project transitioned from GitHub Packages to the public npm registry in version 0.3.0, introducing automated CI/CD workflows for testing, building, and publishing.
Sources: CHANGELOG.md:12-17, README.md:162-165

Release Lifecycle and Automation

The release process is triggered by changes to the repository's main branch. When the version field in package.json is updated and pushed to main, a GitHub Actions workflow automatically handles the publishing process. This automation reduces manual overhead and ensures that every release is subject to the same validation steps.

Automated Workflow Stages

The following diagram illustrates the sequence of events during a release:

The automated workflow ensures that no code is published without passing type checks and unit tests.
Sources: CHANGELOG.md:14-17, README.md:162-165

Build and Package Configuration

The project is configured as a pure ESM (ECMAScript Module) package. Before publishing, the source TypeScript files are compiled into JavaScript and type declarations stored in a dist/ directory.

Core Scripts and Configurations

The package.json file defines several critical scripts that govern the build and validation process:

Script	Command	Purpose
build	tsc	Compiles TypeScript source to the dist directory.
prepublishOnly	npm run build	Ensures the latest code is compiled before any publish event.
check-exports	npx publint && npx @arethetypeswrong/cli --pack .	Validates package exports and type definitions for compatibility.
typecheck	tsc --noEmit	Verifies type safety without generating output files.
test	vitest run	Executes the unit test suite once.

Sources: package.json:44-51, CHANGELOG.md:21-22

Compilation Settings

The project uses NodeNext module resolution to ensure strict ESM compliance. Key settings in tsconfig.json include:

• target: ES2022
• module: NodeNext
• outDir: dist
• verbatimModuleSyntax: true (Enforces modern import/export syntax)

Sources: tsconfig.json:3-13

Export Structure and Validation

To support multiple frameworks (React, Vue, Angular) and core utilities while maintaining tree-shaking capability, the package uses subpath exports.

Subpath Exports

The package defines explicit entry points in package.json. This structure allows users to import only what they need, such as @cellarnode/beverage-utils/react.

"exports": {
  ".": {
    "types": "./dist/index.d.ts",
    "default": "./dist/index.js"
  },
  "./react": {
    "types": "./dist/react/index.d.ts",
    "default": "./dist/react/index.js"
  },
  "./vue": {
    "types": "./dist/vue/index.d.ts",
    "default": "./dist/vue/index.js"
  },
  "./angular": {
    "types": "./dist/angular/index.d.ts",
    "default": "./dist/angular/index.js"
  }
}

Sources: package.json:18-37

Export Integrity

To prevent common "Missing module type" or ESM compatibility errors, the project utilizes publint and @arethetypeswrong/cli. These tools verify that the paths defined in the exports field correctly map to existing files in the dist/ folder and that the type definitions are correctly structured for consumption by various build tools.
Sources: CHANGELOG.md:14-23, package.json:46

Provenance and Security

NPM Provenance is a key security feature of the @cellarnode/beverage-utils publishing process. By publishing with provenance, the project provides a verifiable link between the npm package and the GitHub source code.

Verification Requirements

• Repository URL: The repository.url in package.json must exactly match the GitHub repository (corrected to `git+https://github.com/CellarNode/beverage-utils.git%60 in v0.3.1 to fix casing issues).
• Registry Access: The package is published with access: public to the standard npm registry.
• Side Effects: The package is marked with "sideEffects": false to assist bundlers in tree-shaking, ensuring that only used code is included in the final consumer bundle.

Sources: package.json:10-16, 39, CHANGELOG.md:9-10, 18

Conclusion

The publishing system for @cellarnode/beverage-utils is designed for reliability and transparency. By leveraging GitHub Actions for automated releases, strictly validating exports with publint, and implementing npm provenance, the project ensures that every release is technically sound and securely linked to its source.