Local Development Setup
Relevant source files
The following files were used as context for generating this wiki page:
This page provides the necessary instructions and technical overview for setting up a local development environment for the beverage-utils project. The project is a TypeScript-based utility library providing beverage classification, label mapping, and formatting helpers with adapters for React, Vue, and Angular.
The development environment focuses on a strict ESM (ECMAScript Modules) workflow, utilizing TypeScript for compilation and Vitest for unit testing. It is designed to ensure compatibility across various JavaScript runtimes and frameworks by shipping compiled code and type definitions in a dist/ directory.
Sources: README.md:1-10, package.json:1-30, CHANGELOG.md:12-20
Prerequisites
To contribute to or develop this library, the following environment requirements must be met:
- Node.js: Version
>=20.19.0is required as specified in the engine configuration. - Package Manager:
npmis used for dependency management and script execution.
Sources: package.json:76-78
Initial Environment Setup
The local setup begins with cloning the repository and installing dependencies. Due to the multi-framework nature of the project (React, Vue, and Angular), the installation process uses specific flags to manage peer dependencies.
git clone https://github.com/CellarNode/beverage-utils.git
cd beverage-utils
npm install --legacy-peer-deps
The --legacy-peer-deps flag is utilized during installation to accommodate the various framework peer dependencies required for testing and development of the adapters.
Sources: README.md:175-178, package.json:49-70
Development Workflow and Scripts
The project employs a set of standardized scripts for building, testing, and validating the package.
Build System
The project uses the TypeScript compiler (tsc) to transform source files into production-ready assets. The configuration is defined in tsconfig.json, targeting ES2022 and utilizing NodeNext for module resolution to ensure strict ESM compliance.
| Command | Description |
|---|---|
npm run build | Compiles source files from src/ to the dist/ directory. |
npm run typecheck | Runs the TypeScript compiler in noEmit mode to validate types without generating files. |
Sources: package.json:40-45, tsconfig.json:1-15
Testing and Validation
Testing is handled by vitest. The configuration includes all .test.ts files located within the __tests__ directory.
| Command | Description |
|---|---|
npm test | Executes the test suite once using Vitest. |
npm run test:watch | Starts Vitest in watch mode for continuous testing during development. |
npm run check-exports | Validates package exports using publint and @arethetypeswrong/cli to ensure compatibility. |
Sources: package.json:42-44, vitest.config.ts:1-7
Development Lifecycle Flow
The following diagram illustrates the typical developer workflow from making changes to preparing a release.
Sources: README.md:175-185, package.json:40-45
Build Configuration
The library's output is structured to support different entry points for various frameworks. The tsconfig.json ensures that declarations and source maps are generated for a better developer experience when the library is consumed.
Compilation Parameters
- Target:
ES2022 - Module System:
NodeNext - Strict Mode: Enabled
- Output Directory:
dist - Source Maps: Enabled (including
declarationMap)
Sources: tsconfig.json:3-13, package.json:13-35
Export Structure
The project uses the exports field in package.json to define specific entry points for the core logic and framework adapters.
Sources: package.json:13-35, README.md:15-22
Release and CI/CD
The project includes an automated release process triggered by pushes to the main branch.
- Manual Steps: Developers update
CHANGELOG.mdand bump theversioninpackage.json. - Automated Actions: GitHub Actions perform type-checking, testing, building, and validation (publint). If the version has changed, the package is automatically published to the public npm registry with provenance.
Sources: README.md:187-191, CHANGELOG.md:8-15
Setting up the local environment for beverage-utils ensures that developers can maintain the core classification logic and framework-specific adapters while adhering to strict ESM and TypeScript standards. This setup provides the necessary tooling to validate code quality and package integrity before distribution.