Deterministic, beautiful, and lightweight SVG avatars for everyone.

Live Demo • NPM Package • Documentation

---

📖 About

µAvatar (Micro Avatar) is a dual-purpose project:

1. A standalone NPM library for generating deterministic SVG avatars in any JS environment.
2. A public API service (uavatar.cosmicfi.dev) for generating avatars on the fly via HTTP.

The avatars are generated using a deterministic algorithm based on the input string (username, email, etc.). This means Joe will always generate the exact same avatar, with no database or caching required.

📦 NPM Library

Install the lightweight library to generate avatars directly in your app (Node.js, React, Vue, Svelte, etc.).

npm install uavatar

Usage

import { generateAvatar } from 'uavatar';

// Basic
const svg = generateAvatar('Alice');

// With Options
const svgCircle = generateAvatar('Alice', { 
  shape: 'circle',
  seed: 'custom-seed-if-needed' 
});

See packages/uavatar/README.md for full library documentation.

🌐 HTTP API

You can use the hosted API directly in your <img> tags:

<img src="https://uavatar.cosmicfi.dev/v1/username" alt="User Avatar" />

Parameters:

• shape: square (default) or circle
• seed: Custom seed string (optional)

Example: https://uavatar.cosmicfi.dev/v1/username?shape=circle

🛠️ Development

This repository is a monorepo containing the SvelteKit website/API and the NPM package.

Prerequisites

• Node.js 18+
• NPM

Setup

1. Clone the repository

   git clone https://github.com/cosmic-fi/uavatar.git
   cd uavatar

2. Install dependencies

   npm install

3. Run the Website/API locally

   npm run dev

   The site will be available at http://localhost:5173.

Project Structure

• src/ - The source code for the SvelteKit website and API endpoints.
  • routes/v1/ - The public API route handlers.
  • lib/ - Shared components and logic.
• packages/uavatar/ - The source for the published NPM package.

📄 License

MIT © Cosmic-Fi