Build Configuration
Relevant source files
The following files were used as context for generating this wiki page:
The build configuration for beverage-utils is designed to produce a highly compatible, tree-shakable TypeScript library that supports multiple JavaScript environments and frameworks. It utilizes a standard TypeScript compilation pipeline to transform source code into a distributable package compatible with Node.js, modern bundlers, and framework-specific environments like React, Vue, and Angular.
The project emphasizes strict ESM (ECMAScript Modules) compliance and provides multiple entry points to optimize bundle sizes by allowing consumers to import only the necessary utilities or framework adapters. Sources: package.json, README.md:10-18
Compilation Pipeline
The library is compiled using the TypeScript compiler (tsc). The build process transforms the TypeScript source files located in the src directory into JavaScript and type definitions in the dist directory. This ensures compatibility with tools like Turbopack and Next.js that require compiled assets rather than raw TypeScript files. Sources: tsconfig.json:14-15, CHANGELOG.md:14-15
TypeScript Configuration
The project uses a modernized tsconfig.json optimized for NodeNext module resolution. This configuration is essential for maintaining strict ESM compliance, which includes the requirement for .js extensions in relative imports. Sources: tsconfig.json:4-5, CHANGELOG.md:18-19
| Option | Value | Description |
|---|---|---|
target | ES2022 | Sets the JavaScript language version for produced JavaScript. |
module | NodeNext | Specifies what module code is generated. |
moduleResolution | NodeNext | Determines how modules are resolved. |
verbatimModuleSyntax | true | Simplifies how TypeScript handles imports and exports. |
declaration | true | Generates .d.ts files for the library. |
sideEffects | false | Enables better tree-shaking for consumers. |
Sources: tsconfig.json:3-10, package.json:45
Build Flow Diagram
This diagram illustrates the sequence from source development to the final NPM distribution package.
The build flow ensures that all exports are validated for correctness before reaching the registry. Sources: package.json:52-59, CHANGELOG.md:23-24
Package Exports and Entry Points
The project defines multiple entry points in package.json to support the core library and its various framework-specific adapters. This structure allows the library to be consumed via distinct import paths.
| Import Path | Targeted Environment |
|---|---|
@cellarnode/beverage-utils | Core TypeScript utilities (Zero dependencies) |
@cellarnode/beverage-utils/react | React-specific hooks and query options |
@cellarnode/beverage-utils/vue | Vue-specific composables and query options |
@cellarnode/beverage-utils/angular | Angular-specific services and query options |
Sources: package.json:19-38, README.md:10-18
Dependency Management
The project utilizes peerDependencies to manage framework integrations. This prevents the library from installing multiple versions of frameworks like React or Vue in the consumer's project. All framework-specific dependencies are marked as optional. Sources: package.json:61-71, package.json:73-91
Quality Assurance and Testing
The build configuration includes several scripts for maintaining code quality, ensuring type safety, and validating package integrity.
The test environment is powered by Vitest, configured to target files ending in .test.ts within the __tests__ directory. Sources: vitest.config.ts:3-7, package.json:57
Build Scripts Reference
| Script | Command | Purpose |
|---|---|---|
build | tsc | Compiles the project into the dist folder. |
typecheck | tsc --noEmit | Validates TypeScript types without generating files. |
test | vitest run | Executes the test suite once. |
check-exports | npx publint && npx @arethetypeswrong/cli --pack . | Checks for packaging and ESM compatibility errors. |
prepublishOnly | npm run build | Ensures the latest code is compiled before publishing to NPM. |
Sources: package.json:52-59
Distribution and Release
The library is published to the public NPM registry using GitHub Actions. The automation workflow triggers on pushes to the main branch when a version change is detected in package.json. The release process includes generating provenance and verifying repository URL casing for security and authenticity. Sources: CHANGELOG.md:10-13, README.md:180-184
The final dist folder contains:
- Compiled JS: Modern ESM code.
- Declarations:
.d.tsfiles for full IDE type support. - Source Maps:
.js.mapand.d.ts.mapfiles to facilitate debugging in consuming applications.
Sources: tsconfig.json:7-8, CHANGELOG.md:21-22