Contributing Guidelines

Relevant source files

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

• README.md
• package.json
• packages/avatar/build.config.ts
• packages/avatar/package.json
• packages/avatar/src/core/utils/svg.ts
• packages/avatar/src/open-peeps/components/face.ts
• packages/avatar/src/open-peeps/components/facialHair.ts
• packages/avatar/src/open-peeps/index.ts
• packages/avatar/test/unit/index.test.ts
• vitest.config.ts

This document provides a comprehensive guide for contributing to the @nextorders/avatar project. The project is a monorepo designed to generate personalized SVG avatars based on the Open Peeps illustration set. Adhering to these guidelines ensures a smooth and consistent development workflow.

The contribution process covers setting up the development environment, following coding standards, writing and running tests, and submitting changes. The project utilizes a modern TypeScript toolchain, including pnpm for package management, Vitest for testing, and ESLint for code quality.

1. Getting Started

1.1. Prerequisites

Before you begin, ensure your development environment meets the following requirements as specified in the root package.json:

Tool	Required Version
Node.js	>=24.11.0
pnpm	>=10.20.0

Sources: package.json:13-16

1.2. Project Setup

The project is a pnpm-based monorepo. To set up the development environment, clone the repository and install the dependencies from the root directory.

git clone https://github.com/nextorders/avatar.git
cd avatar
pnpm install

Sources: package.json:5

1.3. Key Scripts

The root package.json contains scripts for managing the monorepo.

Script	Description
build	Executes the build script in each package of the monorepo.
lint / lint:fix	Lints the entire codebase and optionally fixes issues.
clean	Executes the clean script in each package.
typecheck	Runs the TypeScript compiler to check types across all packages.
test	Runs the entire test suite (unit and browser).
test:watch	Runs tests in watch mode.
test:coverage	Runs tests and generates a coverage report.
check:full	A comprehensive check that runs linting, type checking, and all tests. This must pass before submitting a PR.
prepare	Installs Husky for git hooks.

Sources: package.json:19-31

2. Development Workflow

2.1. Coding Standards

To maintain code quality and consistency, the project enforces strict coding and commit standards.

• Linting: ESLint is configured with @antfu/eslint-config. All code is automatically formatted and linted on commit via lint-staged.
  Sources: package.json:33, package.json:46-50
• Commit Messages: Commit messages must follow the Conventional Commits specification. This is enforced by commitlint and a Husky git hook.
  Sources: package.json:34, package.json:51-55

2.2. Testing

The project uses Vitest for both unit and browser-based testing.

• Configuration: The test setup is defined in vitest.config.ts and includes two separate projects:
  1. unit: For Node.js environment tests.
  2. browser: For tests requiring a browser, using Playwright.
• Coverage: There is a strict 80% coverage threshold for statements, branches, functions, and lines.
• Running Tests: Use the pnpm test, pnpm test:coverage, or pnpm test:watch scripts.

The following diagram illustrates the testing workflow.

Unit tests for the core createAvatar function can be found in packages/avatar/test/unit/index.test.ts. These tests verify the function's behavior with different options and ensure the output is a valid SVG string.

Sources: packages/avatar/test/unit/index.test.ts

2.3. Build Process

The @nextorders/avatar package is built using unbuild. The configuration in packages/avatar/build.config.ts defines src/index as the entry point and generates TypeScript declaration files. A build:before hook is used to copy the root README.md file into the package's dist directory.

Sources: packages/avatar/build.config.ts:4-13, packages/avatar/package.json:28

3. Adding New Avatar Components

The core of the avatar generation logic resides in assembling SVG components. Contributions of new components (e.g., faces, hair, accessories) are highly encouraged.

3.1. Component Structure

Avatar components are organized by type (e.g., face, facialHair). Each component type is a ComponentGroup object, which maps a component name to a function that returns an SVG path string.

For example, the face component group in packages/avatar/src/open-peeps/components/face.ts is structured as follows:

// packages/avatar/src/open-peeps/components/face.ts
import type { ComponentGroup } from '../types'

export const face: ComponentGroup = {
  angryWithFang: () =>
    `<path ... />`,
  awe: () =>
    `<g ...><path ... /></g>`,
  // ... more face components
}

Sources: packages/avatar/src/open-peeps/components/face.ts:3-6, packages/avatar/src/open-peeps/components/facialHair.ts:4-6

To add a new component, you would:

1. Identify the correct component group file (e.g., face.ts).
2. Add a new key-value pair, where the key is the name of your new component and the value is a function returning the SVG markup as a string.
3. Ensure the SVG markup is properly escaped if necessary, although the library handles this for colors.

3.2. Avatar Generation Flow

The create function for the open-peeps style orchestrates the assembly of the final SVG.

The diagram below shows the sequence of operations when createAvatar is called.

4. Submission Process

All contributions should be submitted as Pull Requests on GitHub.

1. Fork & Branch: Fork the repository and create a new branch for your feature or bugfix.
2. Develop: Make your changes, adhering to the coding standards.
3. Test: Run the full check suite with pnpm run check:full to ensure all tests and quality gates pass.
4. Commit: Commit your changes using a Conventional Commit message.
5. Push & PR: Push your branch to your fork and open a Pull Request against the main branch of the original repository.

The following diagram outlines the contribution workflow.