Getting Started

Relevant source files

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

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

The @nextorders/avatar package is a toolkit for generating personalized SVG avatars. It is based on the "Open Peeps" illustration set by Pablo Stanley. This guide provides instructions on how to install the package, generate your first avatar, and understand the basic architecture of the library.

The primary function of the package is createAvatar, which takes a set of options and returns an SVG string. The generation process is deterministic based on a provided seed string, allowing for consistent avatar generation.

Sources: README.md, packages/avatar/package.json, packages/avatar/src/index.ts

Installation

You can install the library from the npm registry using your preferred package manager.

npm install @nextorders/avatar

Sources: README.md:14-16

Basic Usage

To generate an avatar, import the createAvatar function and call it with a configuration object. The seed property is mandatory and is used to ensure the generated avatar is consistent.

Avatar Options

The createAvatar function accepts an AvatarOptions object with the following properties:

Parameter	Type	Description	Required
seed	string	A string used to seed the random generator.	Yes
gender	Gender ('male' or 'female')	Determines the gender-specific features.	No
clothing	'amber', 'green', 'blue', 'teal', 'pink', 'violet'	Sets the color of the avatar's clothing.	No
emotion	1 to 10	A number representing the facial emotion.	No

Sources: README.md:20-26, packages/avatar/test/unit/index.test.ts:18-22

Example

Here is a basic example of how to generate an avatar SVG string.

import { createAvatar } from '@nextorders/avatar';

const svgString = createAvatar({
  seed: 'my-random-seed',
  gender: 'female',
  clothing: 'pink',
  emotion: 5,
});

console.log(svgString);

Sources: README.md:18-26, packages/avatar/test/unit/index.test.ts:24-33

Architecture Overview

The avatar generation process involves several key functions and modules. The user-facing createAvatar function acts as a high-level wrapper that validates inputs, builds a detailed options object, and calls the core generation logic.

This diagram illustrates the high-level flow from the user's call to the final SVG string output.

Core Components

1. createAvatar(options: AvatarOptions): The main entry point. It validates the user-provided options.
   • Source: packages/avatar/src/index.ts:14
2. buildOptions(data: AvatarOptions): This internal function transforms the simple AvatarOptions into a more complex configuration object required by the core generator. It selects specific configurations for gender, emotion, and clothing color.
   • Source: packages/avatar/src/index.ts:19-29
3. createBaseAvatar(style, options): The core avatar factory function. It takes a style definition (like openPeeps) and the full options object. It manages the pseudo-random number generator (PRNG), calls the style's create method, and applies various SVG transformations.
   • Source: packages/avatar/src/core/index.ts:8
4. openPeeps.create({ prng, options }): This is the style-specific implementation for "Open Peeps". It uses the PRNG to select various SVG components (head, face, facial hair, etc.) and assembles them into the final avatar body.
   • Source: packages/avatar/src/open-peeps/index.ts:12

Generation Sequence

The following sequence diagram details the interactions between the main functions during avatar creation.

SVG Customization

The core generator allows for several SVG transformations which are passed through the buildOptions function. These options provide control over the final appearance of the SVG canvas.

Option	Type	Description	Source File
size	number	Sets the width and height attributes of the SVG.	packages/avatar/src/core/index.ts:29-32
scale	number	Scales the avatar within the viewbox (value is a percentage).	packages/avatar/src/core/index.ts:34-36
flip	boolean	Flips the avatar horizontally.	packages/avatar/src/core/index.ts:38-40
rotate	number	Rotates the avatar by a specified degree.	packages/avatar/src/core/index.ts:42-44
translateX, translateY	number	Moves the avatar horizontally or vertically (value is a percentage).	packages/avatar/src/core/index.ts:46-52
radius	number	Applies a corner radius to the viewbox, creating a clipping mask.	packages/avatar/src/core/index.ts:63-65
backgroundType	string	Type of background: solid, gradientLinear, randomGradientLinear.	packages/avatar/src/core/index.ts:16
backgroundColor	string[]	An array of colors to be used for the background.	packages/avatar/src/core/index.ts:19
backgroundRotation	number[]	Range of degrees for gradient rotation.	packages/avatar/src/core/index.ts:21-27

These transformations are applied by a set of utility functions within packages/avatar/src/core/utils/svg.ts. For example, addScale wraps the SVG body in a <g> tag with a transform attribute.

Sources: packages/avatar/src/core/index.ts:29-65, packages/avatar/src/core/utils/svg.ts

Testing

The project uses vitest for unit testing. The tests verify the behavior of the createAvatar function, such as ensuring it returns a string, handles missing parameters, and produces expected SVG content for a given seed and options.

Key test cases include:

• Verifying that createAvatar is a function.
• Ensuring an error is thrown if the required seed is not provided.
• Checking that the output is a non-empty string for valid inputs.
• Validating that specific options (like emotion or gender) result in predictable SVG path data.

Sources: packages/avatar/test/unit/index.test.ts, vitest.config.ts