TypeScript icon, indicating that this package has built-in type declarations

0.3.0 • Public • Published


This repository contains the Next.js API Routes that can be used to host your own avatars service!

⚠️ In Development Warning ⚠️

This package is still in early development, and it's API is not yet stable. Until a v1.0 release, consider all minor semver releases (v0.x) to be BREAKING.



  1. First, you'll need the @fuelrats/next-adorable-avatars package:
npm install @fuelrats/next-adorable-avatars --save


yarn add @fuelrats/next-adorable-avatars
  1. Create the directory /api/avatars under your /pages directory.
  2. Inside this directory, create a catch all API route named [...slug].js.
    • While the router may be mounted under any api sub-directory, the file MUST be named [...slug].js for the router to properly map route parameters.
  3. Export avatarsRouter from this new API Route:
// /pages/api/avatars/[...slug].js
import avatarsRouter from '@fuelrats/next-adorable-avatars';

export default avatarsRouter()
  1. That's it! Your server will now serve the avatar endpoints!


Assuming your server lives at myserver.com, and you've configured the middleware as above, you now have the following endpoints:

  • myserver.com/api/avatars/:seed
    • returns an avatar for the provided seed.
    • seed can be anything (email, username, md5 hash, as long as it's a valid URI)
    • size defaults to 512x512px
  • myserver.com/api/avatars/:seed/:size
    • returns an avatar for the provided seed at the specified size
    • size must be >=32 && <=512
  • myserver.com/api/avatars/:seed/:size/:format
    • returns an avatar for the provided seed at the specified size and format
    • See below for supported formats
  • myserver.com/api/avatars/random/:size?/:format?
    • returns a random avatar, different each time
    • Optionally accepts size and format options like the endpoints above.
    • e.g. myserver.com/avatars/random/300
  • myserver.com/api/avatars/face/:eyes/:nose/:mouth/:color/:size?/:format?
    • Allows you to generate a custom avatar from the specified parts and color.
    • Optionally accepts size and format options like the endpoints above.
    • Parts accept the value x for a blank part.
    • Parts and color accept the value * for a random value.
    • e.g. myserver.com/api/avatars/face/eyes1/nose2/mouth4/DEADBF/300/jpeg
  • myserver.com/api/avatars/list
    • returns JSON of all valid parts for the custom endpoint above
    • Also contains list of valid output formats.

Using next/image

Using next/image is encouraged by both Vercel and this library, However some considerations should be made.

  1. Using a loader to resolve the avatar URL is recommended. This is mainly to provide convienence.
  2. Consider setting unoptimized to true if your website has a high traffic load, as it may cause a bloated cache over time.
  • A custom server cache strategy is in planning for both short and long term image caching.
import Image from 'next/image'

const avatarLoader = ({ src, width }) => {
    return `/api/avatars/${src}/${width}`

function SomeComponent (props) => {
    return (
            alt="Profile picture of the user"

Supported Output Formats

Format Parameter
webp webp Default
avif avif
gif gif
heif heic, heif
jpeg jpg, jpeg
png png
tiff tiff

NOTE: While TIFF, AVIF, and HEIF are all supported by the renderer, browser support for these formats is limited or non-existant.


If you're developing locally, you'll first need to bootstrap (assumes nvm):

# use correct node version
nvm use

# install dependencies

Then, there are several scripts that will be useful:

# run the unit tests
yarn test

# run both a dev server and eslint
yarn dev

# run a dev server
yarn dev:server

# run eslint
yarn dev:lint

# compile the application
yarn build


Please read the contributors' guide

Open-source Contributors




Package Sidebar


npm i @fuelrats/next-adorable-avatars

Weekly Downloads






Unpacked Size

330 kB

Total Files


Last publish


  • trezy
  • xlexious
  • clapton