Build and Release Process

Relevant source files

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

• package.json
• packages/avatar/build.config.ts
• packages/avatar/package.json
• pnpm-workspace.yaml
• vitest.config.ts
• tsconfig.json
• packages/avatar/src/index.ts

The avatar project is a monorepo managed with pnpm. The build and release processes are standardized across the workspace, utilizing a combination of pnpm workspace commands, TypeScript for type checking, unbuild for package bundling, Vitest for testing, and bumpp for version management and releases. This system ensures a consistent and automated workflow from development to deployment.

The core of the process is defined by scripts in the root package.json file, which orchestrate tasks across all packages within the workspace. The primary package, @nextorders/avatar, has its own specific build configuration that defines how it is bundled for distribution.

Project and Build Configuration

The repository is structured as a pnpm workspace, which includes the main @nextorders/avatar package and a docs package.

Sources: pnpm-workspace.yaml:2-3

Build Tooling

The primary build tool for the @nextorders/avatar package is unbuild. The build process is triggered by the pnpm run build command, which recursively executes the build script in each package. For the @nextorders/avatar package, this script is simply unbuild.

Sources: package.json:13, packages/avatar/package.json:26

Avatar Package Build Configuration

The build configuration for the @nextorders/avatar package is defined in packages/avatar/build.config.ts. It specifies the entry point and a pre-build hook.

• Declaration: true - Generates TypeScript declaration files (.d.ts).
• Entries: ['src/index'] - The main entry point for the build.
• Hooks: A build:before hook copies the root README.md file into the package directory before the build starts.

// packages/avatar/build.config.ts
import { copyFileSync } from 'node:fs'
import { defineBuildConfig } from 'unbuild'

export default defineBuildConfig({
  declaration: true,
  entries: [
    'src/index',
  ],
  hooks: {
    'build:before': () => {
      // Copy README.md from root
      copyFileSync('../../README.md', './README.md')
    },
  },
})

Sources: packages/avatar/build.config.ts:4-15

Build Output

The build process generates a dist directory within the @nextorders/avatar package. The package.json file defines the package exports, pointing to the generated files.

Export Path	Type	File Path
.	types	./dist/index.d.ts
.	import	./dist/index.mjs
./package.json	-	./package.json
./README.md	-	./README.md

The files array ensures that only the dist directory is included when the package is published.

Sources: packages/avatar/package.json:16-23, packages/avatar/package.json:24-26

Build Flow Diagram

This diagram illustrates the high-level build process for the @nextorders/avatar package.

Testing

Testing is managed by Vitest and is a crucial part of the CI/CD pipeline. The configuration in vitest.config.ts defines two separate test projects: unit and browser.

• Unit Tests: Run in a node environment.
• Browser Tests: Run using @vitest/browser-playwright with chromium in headless mode.

The configuration also enforces coverage thresholds of 80% for statements, branches, functions, and lines.

Sources: vitest.config.ts:5-40

Test Scripts

Script	Description
test	Runs all tests once (vitest run).
test:watch	Runs tests in watch mode.
test:coverage	Runs tests and generates a coverage report.
check:full	A comprehensive check that includes linting, type checking, and running tests.

Sources: package.json:22-25

Testing Process Flow

The following diagram shows how tests are executed.

Release Process

The release process is automated using the bumpp tool, which handles version bumping, changelog generation, and git tagging.

Release Scripts

The main release command is pnpm run release.

// package.json:15-16
"scripts": {
  ...
  "release": "bumpp --execute=\"pnpm run release:prepare\" --recursive",
  "release:prepare": "pnpm run build:types",
  ...
}

The release script uses bumpp to recursively manage versions across the monorepo. Before bumpp commits the version change, it executes the release:prepare script. This script, in turn, runs pnpm run build:types, which executes tsc --emitDeclarationOnly to ensure all TypeScript declaration files are up-to-date.

Sources: package.json:14-16, tsconfig.json:20-22

Release Flow Diagram

This sequence diagram details the steps involved in creating a new release.

Key Dependencies

The build and release process relies on several key development dependencies, which are managed centrally in pnpm-workspace.yaml.

Dependency	Version	Role
bumpp	^10.3.1	Interactive version bumper for releases.
unbuild	^3.6.1	Build tool for bundling the package.
typescript	^5.9.3	For type checking and declaration generation.
vitest	^4.0.3	Test runner.
@vitest/browser-playwright	^4.0.3	Vitest provider for browser testing.
@vitest/coverage-v8	^4.0.3	Coverage reporting for Vitest.
eslint	^9.38.0	Linter for code quality.
@commitlint/cli	^20.1.0	Linter for commit messages.

Sources: pnpm-workspace.yaml:6-24, package.json:28-42

Summary

The build and release process for the avatar repository is a well-defined, automated system leveraging modern tooling within a pnpm monorepo. unbuild handles the creation of distributable package files, Vitest ensures code quality through unit and browser testing with strict coverage goals, and bumpp automates the versioning and release workflow. This entire process is orchestrated through a clear set of pnpm scripts, providing a streamlined experience for developers.