gravi: Gravatar URL Generator

gravi generates Gravatar URLs using sha256 hashes with support for various options.

It has no dependencies and works in node.js and the browser.

Installation

npm install gravi

Usage

Generating a Basic Gravatar URL

For a basic Gravatar URL, you only need to provide an email address.

import { generateGravatarUrl } from 'gravi';

const email = '[email protected]';

const url = await generateGravatarUrl(email);
console.log(url); // Default URL: https://www.gravatar.com/avatar/b4c9a289323b21a01c3e940f150eb9b8c542587f1abfd8f0e1cc1ffc5e475514

Adding Options

You can customize the Gravatar URL with various options like size, default image, rating, forced default image, file extension, protocol, and base URL.

import { generateGravatarUrl, GenerateGravatarUrlOptions } from 'gravi';

const email = '[email protected]';

const options: GenerateGravatarUrlOptions = {
  size: 200,
  default: 'identicon',
  rating: 'pg',
  forcedefault: 'y',
  extension: 'jpg',
  protocol: 'http',
  baseUrl: 'http://custom.gravatar.com/avatar/',
};

const url = await generateGravatarUrl(email, options);
console.log(url); // Custom URL: http://custom.gravatar.com/avatar/b4c9a289323b21a01c3e940f150eb9b8c542587f1abfd8f0e1cc1ffc5e475514.jpg?s=200&d=identicon&r=pg&f=y

Handling Null or Undefined Emails

If the email is null, undefined, or not a string, the function will use a default hash.

import { generateGravatarUrl } from 'gravi';

const undefinedEmail = undefined;

const url = await generateGravatarUrl(undefinedEmail);
console.log(url); // Default hash URL: https://www.gravatar.com/avatar/000000000000000000000000000000000000000000000000000000

Using with Multiple Options

You can combine various options to create highly customized Gravatar URLs.

import { generateGravatarUrl, GenerateGravatarUrlOptions } from 'gravi';

const email = '[email protected]';

const options: GenerateGravatarUrlOptions = {
  size: 150,
  default: 'retro',
  rating: 'g',
  forcedefault: 'n',
  extension: 'png',
  protocol: 'https',
  baseUrl: 'https://secure.gravatar.com/avatar/',
};

const url = await generateGravatarUrl(email, options);
console.log(url); // Custom URL: https://secure.gravatar.com/avatar/b4c9a289323b21a01c3e940f150eb9b8c542587f1abfd8f0e1cc1ffc5e475514.png?s=150&d=retro&r=g&f=n

API

generateGravatarUrl(email: string, options: GenerateGravatarUrlOptions = {})

Parameters

• email (string | null | undefined): The email address for which to generate the Gravatar URL.
• options (GenerateGravatarUrlOptions): An optional object containing Gravatar options.

GenerateGravatarUrlOptions

• size (number): The size of the Gravatar image.
• default (string): URL or one of the built-in defaults (404, mp, identicon, monsterid, wavatar, retro, robohash, blank).
• rating ('g' | 'pg' | 'r' | 'x'): The rating of the Gravatar image.
• forcedefault ('y' | 'n'): Force the default Gravatar image to always be used.
• extension ('jpg' | 'png' | 'gif'): File extension for the Gravatar image.
• protocol ('http' | 'https'): The protocol to use. Default is https.
• baseUrl (string): The base URL for the Gravatar service. Default is <protocol>://www.gravatar.com/avatar/.

Returns

A Promise<string> that resolves to the generated Gravatar URL. If the email is null, undefined, or not a string, a default hash is used.