Skip to content

Versions & Support

Supported versions

LineStatusNotes
3.xSupportedCurrent. Install this.
2.xUnsupportedOnly 2.0.0 reached npm, and it cannot be loaded by Node
1.xUnsupportedDifferent API; superseded by the 2.0 rewrite

Why v2 should not be used

The 2.x tarballs on npm are broken in a way that a green build does not reveal:

  • Every package shipped ESM output without "type": "module", so require() failed on the export keyword.
  • tsc emitted extensionless relative specifiers (from "./random"), so import failed with ERR_MODULE_NOT_FOUND.

Only a bundler resolving extensionless imports could load them, which is why the repository’s own playgrounds never caught it. Packages are now built with tsup and ship ESM + CommonJS with correct extensions, a conditional exports map, and per-condition type declarations.

The catalogue was also incomplete. Versions 2.1.0 through 2.6.0 — which added the abstract, emoji, animals and gradient styles and the Vue, Svelte and web component wrappers — were developed but never published. npm only ever held 2.0.0 of core, style-initials and react. 3.0.0 is the first release that actually carries all seventeen packages.

Why v1 should not be used

v1 had a different API altogether: createAvatar({ name }) returned a DOM element with CSS-styled initials, there was one style, and nothing was deterministic SVG. The 2.0 rewrite replaced it, and v3 keeps that API.

The v1 entry point survives in core as createAvatarElement, deprecated, so a v1 codebase can migrate incrementally. It calls document.createElement, so it throws during server-side rendering. See the Migration Guide.

When avatars change appearance

A seed always gives the same avatar within a release, on any machine. A release can still redraw a style: 3.1.0 redrew all eleven, so every seed looks different from 3.0.x. The release notes say when this happens.

If an avatar’s exact bytes must never change, for example because you hash or cache them forever, pin an exact version rather than a ^ range.

What the version number covers

All eighteen packages — @avatar-generator/core, the eleven style packages, the five framework wrappers and create-avatar-style — are released together from one fixed version group. @avatar-generator/react@3.0.0 is always meant to be used with @avatar-generator/core@3.0.0 and @avatar-generator/style-faces@3.0.0.

They had drifted to 2.0.0 / 2.4.0 / 2.5.0 before 3.0.0 aligned them, so a matched set is a deliberate guarantee rather than a coincidence.

Releases follow semantic versioning, with one clarification specific to a deterministic avatar library:

Requirements

RequirementValue
Node.js18 or newer
Module formatsESM and CommonJS (@avatar-generator/angular is ESM-only)
TypeScriptDeclarations ship per condition; no skipLibCheck workaround needed
Runtime depsNone — core has no dependencies

Framework wrappers declare their framework as a peer dependency:

PackagePeer range
@avatar-generator/reactreact@^18 || ^19
@avatar-generator/vuevue@^3
@avatar-generator/sveltesvelte@^4 || ^5
@avatar-generator/angular@angular/core@^17 || ^18 || ^19 || ^20 || ^21
@avatar-generator/web-componentnone — standard custom element

@avatar-generator/angular ships Angular Package Format (FESM2022, partial Ivy), which Angular has required of libraries since v13 and which is ESM-only, so that package has no require() entry point.

Pinning a matched set

Because the packages move together, install them at the same version:

Terminal window
npm install @avatar-generator/core@3 @avatar-generator/style-initials@3 @avatar-generator/react@3

Style packages depend on core directly, so a package manager will pull a compatible core for you — but you import createAvatar from core yourself, so declare it explicitly rather than relying on a transitive install.

Verification that ships with each release

Every published tarball is built and checked in CI before it goes out:

  • publint --strict on the manifest and attw on type resolution
  • A smoke test that packs all eighteen packages, installs the tarballs into a throwaway project, loads each from real Node as both ESM and CommonJS, generates an avatar from every style, and compiles the published Svelte component with no preprocessor configured
  • Publication only from a version tag that matches every package’s version, with npm provenance

The 3.0.0 packages are an exception: they were published by hand rather than by the release workflow, so they have no npm provenance attestation.

These exist because 2.x shipped without them. See Contributing for how to run them locally.

Built by · MIT licensed