@fuelrats/next-adorable-avatars
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.
Prerequisites
-
Next.js version
>=v9.5.0
Installation
- First, you'll need the
@fuelrats/next-adorable-avatars
package:
npm install @fuelrats/next-adorable-avatars --save
or
yarn add @fuelrats/next-adorable-avatars
- Create the directory
/api/avatars
under your/pages
directory. - 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.
- While the router may be mounted under any api sub-directory, the file MUST be named
- Export
avatarsRouter
from this new API Route:
// /pages/api/avatars/[...slug].js
import avatarsRouter from '@fuelrats/next-adorable-avatars';
export default avatarsRouter()
- That's it! Your server will now serve the avatar endpoints!
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
- returns an avatar for the provided
-
myserver.com/api/avatars/:seed/:size
- returns an avatar for the provided
seed
at the specifiedsize
-
size
must be>=32 && <=512
- returns an avatar for the provided
-
myserver.com/api/avatars/:seed/:size/:format
- returns an avatar for the provided
seed
at the specifiedsize
andformat
- See below for supported formats
- returns an avatar for the provided
-
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.
next/image
Using Using next/image
is encouraged by both Vercel and this library, However some considerations should be made.
- Using a loader to resolve the avatar URL is recommended. This is mainly to provide convienence.
- Consider setting
unoptimized
totrue
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 (
<Image
unoptimized
loader={avatarLoader}
src={props.id}
alt="Profile picture of the user"
width={200}
height={200}
/>
)
}
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.
Development
If you're developing locally, you'll first need to bootstrap (assumes nvm):
# use correct node version
nvm use
# install dependencies
yarn
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
Contributing
Please read the contributors' guide
Open-source Contributors
- missingdink: Illustrated the very first avatars! Check them out!