),
{
width: 1200,
height: 630,
// Add fonts for better typography (optional but recommended)
fonts: [
{
name: 'Inter',
data: await fetch(
new URL('https://fonts.googleapis.com/css2?family=Inter:wght@400;600;800&display=swap')
).then((res) => res.arrayBuffer()),
style: 'normal',
weight: 400,
},
],
}
);
} catch (error) {
console.error('Error generating OG image:', error);
// Return a fallback image on error
return new ImageResponse(
(
Something went wrong
),
{ width: 1200, height: 630 }
);
}
}
```
## Step 3: Create Type-Safe Utility Functions
Create the file: **`lib/og-image.ts`**
```typescript
// Define supported page types
export type PageType = 'homepage' | 'service' | 'blog' | 'blogArticle' | 'about' | 'contact';
export interface OgImageParams {
type?: PageType;
title: string;
subtitle?: string;
image?: string; // filename relative to public folder
}
/**
* Generates a URL for dynamic OG image generation
* @param params - Configuration for the OG image
* @returns Complete URL for the OG image endpoint
*/
export function getOgImageUrl({
type = 'homepage',
title,
subtitle,
image
}: OgImageParams): string {
const baseUrl = process.env.NEXT_PUBLIC_BASE_URL || 'https://yourdomain.com';
const endpoint = `${baseUrl}/api/og`;
const params = new URLSearchParams({
type: type.toString(),
title: title.trim(),
});
if (subtitle?.trim()) {
params.append('subtitle', subtitle.trim());
}
if (image?.trim()) {
params.append('image', image.trim());
}
return `${endpoint}?${params.toString()}`;
}
/**
* Utility to truncate text for better OG image display
*/
export function truncateText(text: string, maxLength: number): string {
if (text.length <= maxLength) return text;
return text.substring(0, maxLength).trim() + '...';
}
/**
* Generate metadata object with OG image for Next.js generateMetadata
*/
export function generateOgMetadata({
title,
description,
ogImageParams
}: {
title: string;
description: string;
ogImageParams: OgImageParams;
}) {
return {
title,
description,
openGraph: {
title,
description,
images: [
{
url: getOgImageUrl(ogImageParams),
width: 1200,
height: 630,
alt: title,
},
],
},
twitter: {
card: 'summary_large_image',
title,
description,
images: [getOgImageUrl(ogImageParams)],
},
};
}
```
## Step 4: Implement in Different Page Types
#### Homepage Example
**`app/page.tsx`**
```tsx
import { generateOgMetadata } from '@/lib/og-image';
export async function generateMetadata() {
return generateOgMetadata({
title: 'Your Business Name - Professional Services',
description: 'We provide top-quality services to help your business grow and succeed.',
ogImageParams: {
type: 'homepage',
title: 'Your Business Name',
subtitle: 'Professional Services That Deliver Results',
image: 'hero-background.jpg', // Optional: file in /public folder
},
});
}
export default function HomePage() {
return (
Welcome to Your Business
{/* Your homepage content */}
);
}
```
### Blog Article Example
**`app/blog/[slug]/page.tsx`**
```tsx
import { generateOgMetadata, truncateText } from '@/lib/og-image';
// Mock function - replace with your actual blog post fetching logic
async function getBlogPost(slug: string) {
// Your blog post fetching logic here
return {
title: 'Understanding ADHD: A Complete Guide',
excerpt: 'Learn about ADHD symptoms, diagnosis, and treatment options in this comprehensive guide.',
author: 'Dr. Jane Smith',
publishedAt: '2024-01-15',
featuredImage: 'adhd-guide-bg.jpg',
content: '...',
};
}
export async function generateMetadata({
params
}: {
params: { slug: string }
}) {
const post = await getBlogPost(params.slug);
return generateOgMetadata({
title: post.title,
description: post.excerpt,
ogImageParams: {
type: 'blogArticle',
title: truncateText(post.title, 60), // Ensure it fits nicely
subtitle: truncateText(post.excerpt, 120),
image: post.featuredImage,
},
});
}
export default async function BlogPostPage({
params
}: {
params: { slug: string }
}) {
const post = await getBlogPost(params.slug);
return (
{post.title}
{post.excerpt}
{/* Your blog post content */}
);
}
```
### Service Page Example
**`app/services/[serviceSlug]/page.tsx`**
```tsx
import { generateOgMetadata } from '@/lib/og-image';
const services = {
'web-development': {
title: 'Web Development Services',
description: 'Custom web development solutions for modern businesses.',
features: ['Responsive Design', 'Performance Optimization', 'SEO Ready'],
backgroundImage: 'web-dev-bg.jpg',
},
'digital-marketing': {
title: 'Digital Marketing Services',
description: 'Grow your online presence with our digital marketing expertise.',
features: ['SEO', 'Social Media', 'Content Marketing'],
backgroundImage: 'marketing-bg.jpg',
},
};
export async function generateMetadata({
params
}: {
params: { serviceSlug: string }
}) {
const service = services[params.serviceSlug as keyof typeof services];
if (!service) {
return { title: 'Service Not Found' };
}
return generateOgMetadata({
title: service.title,
description: service.description,
ogImageParams: {
type: 'service',
title: service.title,
subtitle: service.description,
image: service.backgroundImage,
},
});
}
export default function ServicePage({
params
}: {
params: { serviceSlug: string }
}) {
const service = services[params.serviceSlug as keyof typeof services];
if (!service) {
return
Service not found
;
}
return (
{service.title}
{service.description}
{/* Your service page content */}
);
}
```
## Step 5: Environment Configuration
Add to your **`.env.local`**:
```env
NEXT_PUBLIC_BASE_URL=https://yourdomain.com
# For local development, use: http://localhost:3000
```
Update your **`robots.txt`** in the `public` folder:
```txt
User-agent: *
Allow: /
# Allow OG image generation
Allow: /api/og/*
Sitemap: https://yourdomain.com/sitemap.xml
```
# Testing Your Implementation
## 1. Local Testing
Start your development server:
```bash
npm run dev
```
Test the OG endpoint directly:
- `http://localhost:3000/api/og?type=homepage&title=Welcome&subtitle=This is our homepage`
- `http://localhost:3000/api/og?type=blogArticle&title=My Blog Post&subtitle=This is a great article`
## 2. Social Media Testing
Use these tools to test your OG images:
- **Facebook**: [Sharing Debugger](https://developers.facebook.com/tools/debug/)
- **Twitter**: [Card Validator](https://cards-dev.twitter.com/validator)
- **LinkedIn**: [Post Inspector](https://www.linkedin.com/post-inspector/)
- **General**: [OpenGraph.xyz](https://www.opengraph.xyz/)
# Advanced Enhancements
## Custom Fonts
Add custom fonts to your OG images:
```tsx
// In your route.tsx, add fonts to ImageResponse options
{
fonts: [
{
name: 'CustomFont',
data: await fetch(new URL('./assets/CustomFont.ttf', import.meta.url)).then(
(res) => res.arrayBuffer()
),
style: 'normal',
weight: 700,
},
],
}
```
## Theme Support
Add light/dark theme support:
```tsx
const theme = searchParams.get('theme') || 'light';
const isDark = theme === 'dark';
// Use in your styles
background: isDark ? 'linear-gradient(135deg, #1f2937 0%, #111827 100%)' : styles.bg,
color: isDark ? '#f3f4f6' : 'white',
```
## Caching and Performance
Add caching headers in your route:
```tsx
export async function GET(req: NextRequest) {
const response = new ImageResponse(/* ... */);
// Cache for 1 hour
response.headers.set('Cache-Control', 'public, max-age=3600, stale-while-revalidate=86400');
return response;
}
```
# Best Practices
1. **Image Dimensions**: Stick to 1200x630 for optimal compatibility
2. **File Size**: Keep generated images under 1MB
3. **Text Length**: Limit titles to ~60 characters, subtitles to ~120
4. **Error Handling**: Always provide fallback images
5. **Performance**: Use Edge Runtime for faster generation
6. **SEO**: Include both OpenGraph and Twitter Card meta tags
7. **Testing**: Test across multiple social platforms before deploying
# Troubleshooting
**Common Issues:**
- **Images not loading**: Check your `NEXT_PUBLIC_BASE_URL` environment variable
- **Fonts not rendering**: Ensure font files are accessible and properly loaded
- **Social platforms not showing new images**: Clear their cache using platform-specific debugging tools
- Use the [Facebook Debugger](https://developers.facebook.com/tools/debug/) or [Twitter Card Validator](https://cards-dev.twitter.com/validator)
- **Build errors**: Make sure you're using Next.js 13.4+ with App Router
Your Next.js 15 app now generates beautiful, dynamic OG images that will significantly improve your social media engagement and click-through rates!
## LLM Response Snippet
```json
{
"goal": "Learn how to implement dynamic Open Graph image generation in Next.js 15.4+ using Vercel’s OG Image tool.",
"responses": [
{
"question": "What does the article \"How to Automatically Generate Unique OG Images for Every Page in Next.js 15.4+\" cover?",
"answer": "Learn how to implement dynamic Open Graph image generation in Next.js 15.4+ using Vercel’s OG Image tool."
}
]
}
```