Installation

Get astro-gravatar installed and running in your Astro project.

Prerequisites

Astro project (version 4, 5, or 6)
Node.js 22.12+ or Bun
Package manager (npm, yarn, pnpm, or Bun)

Install Package

Choose your preferred package manager:

# Using npm
npm install astro-gravatar

# Using yarn
yarn add astro-gravatar

# Using pnpm
pnpm add astro-gravatar

# Using Bun (recommended)
bun add astro-gravatar

Basic Setup

1. Import Components

---
import GravatarAvatar from 'astro-gravatar';
import GravatarProfileCard from 'astro-gravatar/GravatarProfileCard';
---

2. Add Your First Avatar

---
import GravatarAvatar from 'astro-gravatar';
---

<GravatarAvatar
  email="user@example.com"
  size={80}
  class="rounded-full"
/>

3. Verify Installation

Run your development server:

# Using npm
npm run dev

# Using Bun (recommended)
bun run dev

Visit your site and you should see the Gravatar avatar display.

Environment Setup (Optional)

For enhanced profile features, add your Gravatar API key:

# .env file
GRAVATAR_API_KEY=your-api-key-here

Get your API key from gravatar.com/developers.

Adding the variable to .env does not automatically authenticate requests on its own. Pass it into getProfile, getProfiles, or GravatarClient when you make profile requests:

import { getProfile } from 'astro-gravatar';

const profile = await getProfile('user@example.com', {
  apiKey: import.meta.env.GRAVATAR_API_KEY,
});

For larger applications, the same environment variable can be wired into GravatarClient:

import { GravatarClient } from 'astro-gravatar';

const client = new GravatarClient({
  apiKey: import.meta.env.GRAVATAR_API_KEY,
});

TypeScript Support

TypeScript types are included automatically. No additional setup needed.

Next Steps

Quick Start Guide - Learn the basics
Basic Usage - See common patterns
CLI Guide - Generate URLs from the terminal
Authentication - Set up API keys
Component Reference - Complete API docs

Troubleshooting

Module not found error?

Ensure you’re using a supported Astro version (^4 || ^5 || ^6)
Restart your development server
Check that node_modules/astro-gravatar exists

Avatar not showing?

Verify the email address is valid
Check browser console for errors
Try adding a default avatar: default="identicon"

TypeScript errors?

Make sure your editor is using the workspace TypeScript version
Restart your TypeScript language server