The express middleware for our avatars service
Clone or download
Latest commit 5a707fc Apr 24, 2018


Build Status

What is it?

This repository contains the express middleware that can be used to host your own avatars service!

Check out our website for more info on (and an interactive demo of) what this service does.

How do I use it?

First, you'll need to install the package:

npm install adorable-avatars --save

Then, use the router middleware within your application:

// your_server.js
import express from 'express';
import avatarsMiddleware from 'adorable-avatars';

const myApp = express();
myApp.use('/myAvatars', avatarsMiddleware);

That's it! Your server now includes the avatars endpoints!


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

    • returns an avatar for the provided id.
    • id can be anything (email, username, md5 hash, as long as it's a valid URI)
    • defaults to 400px
    • returns an avatar for the provided id at the specified size
    • size cannot exceed 400px
    • Allows you to generate a custom avatar from the specified parts and color, and size
    • e.g.
    • returns JSON of all valid parts for the custom endpoint above
      • returns a random avatar, different each time
      • e.g.


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

# use correct node version
nvm use

# install dependencies
npm install

Then, there are several npm scripts that will be useful:

# run the unit tests
npm test

# run a dev server
npm start

# run both a dev server and eslint
npm run dev

# compile the application
npm run build

# run the compiled server
npm run start:prod


Please read the contributors' guide

Open-source Contributors