Troubleshooting
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
- 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
- tsconfig.json
- vitest.config.ts
This document provides guidance for diagnosing and resolving common issues encountered while working with the @nextorders/avatar repository. It covers problems related to avatar generation, the development environment, build processes, and testing. The solutions and diagnostic steps described here are derived directly from the project's source code and configuration files.
The primary areas for troubleshooting are avatar rendering logic, environment and build configuration, and the testing framework. Understanding how these systems are configured is key to resolving most issues.
Avatar Generation Issues
Problems in this category typically manifest as incorrect or malformed SVG output. This can range from a complete failure to generate an avatar to subtle visual glitches in specific components.
Missing or Incorrect SVG Output
The most common issues are related to invalid input for the createAvatar function or errors in the underlying SVG component data.
Common Cause 1: Missing seed Parameter
The createAvatar function requires a seed property in its options object to ensure deterministic generation. If the seed is not provided, the function will throw an error.
Sources: packages/avatar/test/unit/index.test.ts:18-24
Common Cause 2: Incorrect Component Rendering
If an avatar is generated but a specific feature (like the face or an accessory) appears broken or incorrect, the issue likely lies within the SVG path data for that component. The open-peeps style assembles the final SVG from several component parts.
The following diagram illustrates the high-level data flow for creating an avatar with the open-peeps style.
This diagram shows the process within open-peeps/index.ts from the initial style creation call to the final assembly of the SVG string.
Sources: packages/avatar/src/open-peeps/index.ts:15-21, packages/avatar/src/open-peeps/index.ts:24-30
Unit tests can be used to diagnose these issues. For example, a test confirms that an avatar with emotion: 5 (serious) contains a specific SVG path string. If this test fails, it points to a problem in the serious component definition within packages/avatar/src/open-peeps/components/face.ts.
Sources: packages/avatar/test/unit/index.test.ts:26-29, packages/avatar/src/open-peeps/components/face.ts:213
Incorrect Transformations (Scale, Rotation, Position)
The @nextorders/avatar package provides several utility functions to apply transformations to the generated SVG. If an avatar appears flipped, rotated, or scaled incorrectly, these utilities are the primary area to investigate.
The core transformation logic is located in packages/avatar/src/core/utils/svg.ts.
| Function | Description |
|---|---|
addScale | Scales the avatar relative to its center. |
addRotate | Rotates the avatar around its center. |
addTranslate | Moves the avatar horizontally or vertically. |
addFlip | Flips the avatar horizontally. |
addBackground | Adds a solid or gradient background layer. |
addViewboxMask | Applies a rounded corner mask to the SVG. |
Sources: packages/avatar/src/core/utils/svg.ts
The following diagram shows how these transformations are layered onto the base SVG body.
This diagram shows the order of SVG transformations. An issue with any transformation can be debugged by examining the corresponding function in svg.ts.
Sources: packages/avatar/src/core/utils/svg.ts
Build & Development Environment Issues
These problems relate to the project's setup, including dependencies, TypeScript configuration, and the build process.
Dependency and Version Conflicts
The project specifies required versions for node and pnpm. Using incorrect versions can lead to unexpected errors or failed dependency installations.
| Tool | Required Version |
|---|---|
node | >=24.11.0 |
pnpm | >=10.20.0 |
Sources: package.json:9-12
Type Errors and Import Resolution
The project uses a strict TypeScript configuration. Build or type-check failures are often due to violations of these strict rules. Import resolution issues may stem from incorrect path aliases.
tsconfig.json Option | Value | Implication for Troubleshooting |
|---|---|---|
strict | true | The compiler enforces all strict type-checking rules. |
noUncheckedIndexedAccess | true | Accessing an array element or object property requires an explicit check for undefined. |
paths | {"@nextorders/avatar": [...]} | Defines the import alias for the main package. Errors in resolving this path point to this configuration. |
include / exclude | various | These patterns determine which files are included in the TypeScript compilation. If a file is not being type-checked, verify it matches the include pattern and is not in exclude. |
Sources: tsconfig.json
The diagram below shows the role of tsconfig.json in the development workflow.
This diagram illustrates how the TypeScript compiler uses tsconfig.json to validate the codebase.
Sources: tsconfig.json, package.json:20
Build Failures
The @nextorders/avatar package is built using unbuild. The configuration is in packages/avatar/build.config.ts. A build failure could be related to the entry points or build hooks defined here. For instance, the build process includes a hook to copy the root README.md file into the package directory. A failure in this step would result in a missing README.md in the final package.
Sources: packages/avatar/build.config.ts:5-13
Testing Issues
Problems with running or passing tests can be diagnosed by examining the vitest.config.ts file and the tests themselves.
Tests Not Running or Failing
The project's test suite is configured in vitest.config.ts. It defines separate projects for unit and browser tests, each with specific file path patterns.
- Unit Tests: Run in a
nodeenvironment. Match files like**/test/unit/**/*.test.ts. - Browser Tests: Run in a
playwright(chromium) environment. Match files like**/test/browser/**/*.test.ts.
If a newly added test is not executing, ensure its file path matches one of these include patterns.
Sources: vitest.config.ts:5-29
Additionally, the configuration specifies code coverage thresholds. A build or CI pipeline may fail if these thresholds are not met.
| Metric | Threshold |
|---|---|
statements | 80% |
branches | 80% |
functions | 80% |
lines | 80% |
Sources: vitest.config.ts:31-39
The testing workflow is initiated by the pnpm test command.
This diagram shows how Vitest uses its configuration file to execute different test projects in their respective environments.
Sources: vitest.config.ts, package.json:21
Conclusion
Troubleshooting in the @nextorders/avatar repository generally involves a systematic check of three key areas. For rendering issues, inspect the input to createAvatar and the SVG component data, using unit tests as a guide. For environment and build problems, verify Node/pnpm versions and review the tsconfig.json and build.config.ts files. For testing failures, consult vitest.config.ts to understand test execution rules and coverage requirements. By following these steps, developers can efficiently diagnose and resolve most common problems.