@fuelrats/next-adorable-avatars
    TypeScript icon, indicating that this package has built-in type declarations

    0.3.0 • Public • Published

    @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

    Installation

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

    or

    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!

    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 (
            <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

    Keywords

    none

    Install

    npm i @fuelrats/next-adorable-avatars

    DownloadsWeekly Downloads

    2

    Version

    0.3.0

    License

    MIT

    Unpacked Size

    330 kB

    Total Files

    40

    Last publish

    Collaborators

    • trezy
    • xlexious
    • clapton