Skip to content
The express middleware for our avatars service
Branch: develop
Clone or download
rylnd Merge pull request #88 from adorableio/add-module-exports
Add module.exports for commonJS users.

Closes #86
Latest commit a84eff4 Jan 15, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
test Update test to assert randomness Apr 24, 2018
.babelrc Use the add-module-exports plugin Jan 13, 2019
.gitignore sets up using avatars as a middleware Aug 29, 2017
.travis.yml Update node version to 9.4 Apr 2, 2018
LICENSE Add MIT license Jul 15, 2014
Procfile Point folks to docs to cover more environments than OS X Oct 5, 2018
package-lock.json Update dependencies to fix vulnerabilities Jan 13, 2019
package.json Update dependencies to fix vulnerabilities Jan 13, 2019


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 lone external dependency. Instructions for installing ImageMagick on a wide variety of systems are available at

Mac OS X users can install with homebrew:

brew install imagemagick

Next, you'll need the adorable-avatars 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

You can’t perform that action at this time.