Home
Relevant source files
The following files were used as context for generating this wiki page:- README.md
- package.json
- packages/avatar/package.json
- packages/avatar/src/core/index.ts
- packages/avatar/src/open-peeps/index.ts
- packages/avatar/src/core/utils/svg.ts
- packages/avatar/test/unit/index.test.ts
- vitest.config.ts
- packages/avatar/build.config.ts
- packages/avatar/src/open-peeps/components/face.ts
- packages/avatar/src/open-peeps/components/facialHair.ts
The @nextorders/avatar repository is a monorepo containing a toolkit for generating personalized SVG avatars. The primary package, @nextorders/avatar, provides a createAvatar() function to generate avatars based on a seed and various customization options. The visual style of the avatars is derived from the "Open Peeps" illustration set by Pablo Stanley.
The system is designed to be deterministic, where the same seed and options will always produce the same avatar. It achieves this by using a seeded pseudo-random number generator (PRNG) to select avatar components and colors. The final output is a complete SVG string, which can also be returned as a JSON object with metadata or a Data URI.
Sources: README.md, packages/avatar/package.json:4, packages/avatar/src/core/index.ts:7-11, packages/avatar/src/open-peeps/index.ts:8-13
Project Structure
The repository is a pnpm-based monorepo. The main application logic is contained within the packages/avatar workspace.
Sources: package.json:4-5
This diagram illustrates the monorepo structure.
Sources: package.json, packages/avatar/package.json
Key Scripts
The root package.json defines several scripts for managing the monorepo.
| Script | Description |
|---|---|
build | Runs the build script for all packages in the monorepo. |
test | Runs all tests (unit and browser) using Vitest. |
lint | Lints the entire codebase with ESLint. |
typecheck | Runs TypeScript type checking across all packages. |
release | Manages version bumping and release preparation. |
check:full | A comprehensive check that runs linting, type checking, and tests. |
Sources: package.json:13-25
Core Functionality
The core of the library is the createAvatar function, which orchestrates the avatar generation process. It takes a style definition and a set of options, and returns a result object.
Sources: packages/avatar/src/core/index.ts:6-11
createAvatar Process Flow
The following diagram shows the step-by-step process executed by the createAvatar function.
Avatar Options
The createAvatar function is configured through an AvatarOptions object. A seed is the only required property.
| Option | Type | Description |
|---|---|---|
seed | string | Required. A string used to seed the random number generator for deterministic output. |
gender | Gender | Can be 'male' or 'female'. Influences component selection. |
clothing | 'amber' | 'green' | 'blue' | 'teal' | 'pink' | 'violet' | Sets the color of the clothing. |
emotion | 1 | 2 | ... | 10 | An integer from 1 to 10 that determines the facial expression. |
Sources: README.md:19-25, packages/avatar/test/unit/index.test.ts:25-26, 31-36
Return Value
The createAvatar function returns a Result object with three methods for accessing the generated avatar.
| Method | Return Type | Description |
|---|---|---|
toString() | string | Returns the complete SVG as a string. |
toJson() | object | Returns an object containing the SVG string and extra metadata like colors and component names. |
toDataUri() | string | Returns a data:image/svg+xml;utf8 encoded Data URI. |
Sources: packages/avatar/src/core/index.ts:59-75
Avatar Style: Open Peeps
The library uses a style system to define the look of the avatars. The included open-peeps style is based on the "Open Peeps" illustrations by Pablo Stanley.
Sources: packages/avatar/src/open-peeps/index.ts:8-13
Component Assembly
The open-peeps style's create function assembles the avatar from several component groups. A pseudo-random number generator (PRNG), seeded by the user-provided seed, selects a specific component from each group.
The main component groups are:
headfacefacialHairaccessories
The following sequence diagram illustrates how createAvatar interacts with the open-peeps style to generate the SVG body.
The face and facialHair components, for example, are collections of functions, each returning an SVG path string for a specific variation.
Sources: packages/avatar/src/open-peeps/components/face.ts, packages/avatar/src/open-peeps/components/facialHair.ts
SVG Manipulation
The packages/avatar/src/core/utils/svg.ts file contains a suite of utility functions for programmatically manipulating the generated SVG. These functions are used by createAvatar to apply transformations based on the user options.
| Function | Description |
|---|---|
addBackground() | Adds a solid or gradient background layer to the SVG. |
addScale() | Applies a scaling transformation to the avatar. |
addTranslate() | Applies a translation (move) transformation. |
addRotate() | Rotates the avatar around its center. |
addFlip() | Flips the avatar horizontally. |
addViewboxMask() | Adds a mask to create rounded corners (radius). |
createAttrString() | Constructs the final attribute string for the <svg> tag. |
Sources: packages/avatar/src/core/utils/svg.ts
Build and Test
The project is configured for modern development workflows, including automated builds and testing.
Build Process
The @nextorders/avatar package uses unbuild for its build process. The configuration in build.config.ts specifies that src/index.ts is the entry point and that TypeScript declarations (.d.ts files) should be generated. It also includes a hook to copy the root README.md file into the package directory before building.
Sources: packages/avatar/build.config.ts:4-13
Testing Strategy
Testing is handled by Vitest. The configuration in vitest.config.ts defines two separate test projects:
unit: For Node.js environment tests, located in**/test/unit/**/*.ts.browser: For tests requiring a browser environment, using@vitest/browser-playwrightwith Chromium. These are located in**/test/browser/**/*.ts.
The configuration also enforces coverage thresholds of 80% for statements, branches, functions, and lines.
Sources: vitest.config.ts:4-36, packages/avatar/test/unit/index.test.ts
Summary
The @nextorders/avatar library is a well-structured and tested tool for generating SVG avatars. Its core createAvatar function provides a flexible API that leverages a seeded PRNG for deterministic output. By combining a style system (with the "Open Peeps" style included) and a set of SVG manipulation utilities, it can produce a wide variety of customized avatars from a simple set of options. The monorepo structure and modern tooling (pnpm, Vitest, unbuild) facilitate development and maintenance.