Development Setup

Relevant source files

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

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

The avatar project is a TypeScript monorepo managed with pnpm. The development environment is configured with a modern toolchain to ensure code quality, consistency, and an efficient workflow. This includes tools for linting, type-checking, testing, building, and versioning. The setup is designed to support multiple packages within the repository, with a primary focus on the @nextorders/avatar library.

The environment requires specific versions of Node.js (>=24.11.0) and pnpm (>=10.20.0) to ensure compatibility and stability across development and CI/CD pipelines.

Sources: package.json:9-12

Project Structure

The repository is structured as a pnpm workspace, which allows for managing dependencies and running scripts across multiple packages from the root directory. The workspace configuration is defined in pnpm-workspace.yaml.

Sources: pnpm-workspace.yaml

packages:
  - docs
  - packages/*

Sources: pnpm-workspace.yaml:1-3

This configuration includes the docs directory and all subdirectories within packages as part of the monorepo.

The following diagram illustrates the monorepo structure:

Sources: pnpm-workspace.yaml:1-3

Dependency Management

Dependencies are managed using pnpm catalogs, which centralize version definitions for development and testing tools. This ensures that all packages in the workspace use the same versions of shared dependencies, preventing version conflicts.

catalogs:
  dev:
    '@antfu/eslint-config': ^6.1.0
    '@commitlint/cli': ^20.1.0
    # ... other dev dependencies
    typescript: ^5.9.3
    unbuild: ^3.6.1
  test:
    '@vitest/browser-playwright': ^4.0.3
    '@vitest/coverage-v8': ^4.0.3
    playwright: ^1.56.1
    vitest: ^4.0.3

Sources: pnpm-workspace.yaml:5-20

TypeScript Configuration

The project uses a root tsconfig.json to enforce consistent TypeScript settings across all packages. It is configured for modern JavaScript (ES2022) and uses the Bundler module resolution strategy, which is optimized for modern bundlers.

Key compiler options include:

Option	Value	Description
target	es2022	Compiles to ES2022 JavaScript standard.
module	esnext	Uses the latest ECMAScript module syntax.
moduleResolution	Bundler	Modern module resolution strategy for bundlers.
strict	true	Enables all strict type-checking options.
noUncheckedIndexedAccess	true	Adds undefined to types that are accessed via an index signature.
paths	{ "@nextorders/avatar": [...] }	Defines a path alias for internal package imports.

Sources: tsconfig.json:3-29

The path alias configuration simplifies imports between packages within the monorepo:

"paths": {
  "@nextorders/avatar": ["./packages/avatar/index.ts"],
  "@nextorders/avatar/*": ["./packages/avatar/*"]
}

Sources: tsconfig.json:13-16

Scripts and Workflows

The root package.json contains a set of pnpm scripts to automate common development tasks. These scripts can be run from the root of the repository.

Script	Description
build	Executes the build script in all packages (pnpm -r run build).
lint	Lints the entire codebase using ESLint.
test	Runs all tests using Vitest in run mode.
test:coverage	Runs tests and generates a coverage report.
typecheck	Executes typecheck script in all packages to validate TypeScript types.
check:full	A comprehensive check that runs linting, type-checking, and all tests.
release	Manages package versioning and release preparation using bumpp.
prepare	Installs Git hooks using husky.

Sources: package.json:14-27

The check:full script provides a complete validation cycle, which is useful before committing or pushing changes.

The workflow for the check:full script is as follows:

Sources: package.json:26

Building

The @nextorders/avatar package uses unbuild for the build process. The configuration is located in packages/avatar/build.config.ts.

Key build configurations:

• Entry Point: The build starts from src/index.
• Declaration Files: TypeScript declaration files (.d.ts) are generated (declaration: true).
• Build Hook: Before the build runs, a hook copies the root README.md file into the package's root directory.

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:1-14

The package's package.json defines the build script and specifies the output directory (dist) and exported paths.

Sources: packages/avatar/package.json:24, 29

Testing

The project uses Vitest for testing. The configuration in vitest.config.ts defines two separate test projects:

1. unit: For unit tests running in a node environment.
2. browser: For browser-based tests using @vitest/browser-playwright with Chromium.

This separation allows for testing both server-side logic and client-side rendering behavior.

// vitest.config.ts
export default defineConfig({
  test: {
    projects: [
      {
        // ...
        name: 'unit',
        environment: 'node',
      },
      {
        // ...
        name: 'browser',
        browser: {
          provider: playwright(),
          enabled: true,
          // ...
        },
      },
    ],
    // ...
  },
})

Sources: vitest.config.ts:4-28

The test configuration also enforces a coverage threshold of 80% for statements, branches, functions, and lines, ensuring a high level of test coverage across the codebase.

Sources: vitest.config.ts:30-36

Code Quality

Code quality and consistency are enforced through several tools configured in the root package.json.

• ESLint: Used for static code analysis, configured with @antfu/eslint-config.
• Husky & lint-staged: Git hooks are managed by husky. A pre-commit hook runs lint-staged, which in turn runs eslint --cache --fix on staged files. This ensures that code is formatted and free of linting errors before being committed.
• Commitlint: A commit-msg hook enforces the Conventional Commits specification for commit messages, ensuring a clean and readable git history.

"lint-staged": {
  "*.{js,ts,tsx,vue,md,json}": [
    "eslint --cache --fix"
  ]
},
"commitlint": {
  "extends": [
    "@commitlint/config-conventional"
  ]
}

Sources: package.json:41-51