1# Metadata
2 
3Add SEO metadata to Next.js pages using the Metadata API.
4 
5## Important: Server Components Only
6 
7The `metadata` object and `generateMetadata` function are **only supported in Server Components**. They cannot be used in Client Components.
8 
9If the target page has `'use client'`:
101. Remove `'use client'` if possible, move client logic to child components
112. Or extract metadata to a parent Server Component layout
123. Or split the file: Server Component with metadata imports Client Components
13 
14## Static Metadata
15 
16```tsx
17import type { Metadata } from 'next'
18 
19export const metadata: Metadata = {
20  title: 'Page Title',
21  description: 'Page description for search engines',
22}
23```
24 
25## Dynamic Metadata
26 
27```tsx
28import type { Metadata } from 'next'
29 
30type Props = { params: Promise<{ slug: string }> }
31 
32export async function generateMetadata({ params }: Props): Promise<Metadata> {
33  const { slug } = await params
34  const post = await getPost(slug)
35  return { title: post.title, description: post.description }
36}
37```
38 
39## Avoid Duplicate Fetches
40 
41Use React `cache()` when the same data is needed for both metadata and page:
42 
43```tsx
44import { cache } from 'react'
45 
46export const getPost = cache(async (slug: string) => {
47  return await db.posts.findFirst({ where: { slug } })
48})
49```
50 
51## Viewport
52 
53Separate from metadata for streaming support:
54 
55```tsx
56import type { Viewport } from 'next'
57 
58export const viewport: Viewport = {
59  width: 'device-width',
60  initialScale: 1,
61  themeColor: '#000000',
62}
63 
64// Or dynamic
65export function generateViewport({ params }): Viewport {
66  return { themeColor: getThemeColor(params) }
67}
68```
69 
70## Title Templates
71 
72In root layout for consistent naming:
73 
74```tsx
75export const metadata: Metadata = {
76  title: { default: 'Site Name', template: '%s | Site Name' },
77}
78```
79 
80## Metadata File Conventions
81 
82Reference: https://nextjs.org/docs/app/getting-started/project-structure#metadata-file-conventions
83 
84Place these files in `app/` directory (or route segments):
85 
86| File | Purpose |
87|------|---------|
88| `favicon.ico` | Favicon |
89| `icon.png` / `icon.svg` | App icon |
90| `apple-icon.png` | Apple app icon |
91| `opengraph-image.png` | OG image |
92| `twitter-image.png` | Twitter card image |
93| `sitemap.ts` / `sitemap.xml` | Sitemap (use `generateSitemaps` for multiple) |
94| `robots.ts` / `robots.txt` | Robots directives |
95| `manifest.ts` / `manifest.json` | Web app manifest |
96 
97## SEO Best Practice: Static Files Are Often Enough
98 
99For most sites, **static metadata files provide excellent SEO coverage**:
100 
101```
102app/
103├── favicon.ico
104├── opengraph-image.png     # Works for both OG and Twitter
105├── sitemap.ts
106├── robots.ts
107└── layout.tsx              # With title/description metadata
108```
109 
110**Tips:**
111- A single `opengraph-image.png` covers both Open Graph and Twitter (Twitter falls back to OG)
112- Static `title` and `description` in layout metadata is sufficient for most pages
113- Only use dynamic `generateMetadata` when content varies per page
114 
115---
116 
117# OG Image Generation
118 
119Generate dynamic Open Graph images using `next/og`.
120 
121## Important Rules
122 
1231. **Use `next/og`** - not `@vercel/og` (it's built into Next.js)
1242. **No searchParams** - OG images can't access search params, use route params instead
1253. **Avoid Edge runtime** - Use default Node.js runtime
126 
127```tsx
128// Good
129import { ImageResponse } from 'next/og'
130 
131// Bad
132// import { ImageResponse } from '@vercel/og'
133// export const runtime = 'edge'
134```
135 
136## Basic OG Image
137 
138```tsx
139// app/opengraph-image.tsx
140import { ImageResponse } from 'next/og'
141 
142export const alt = 'Site Name'
143export const size = { width: 1200, height: 630 }
144export const contentType = 'image/png'
145 
146export default function Image() {
147  return new ImageResponse(
148    (
149      <div
150        style={{
151          fontSize: 128,
152          background: 'white',
153          width: '100%',
154          height: '100%',
155          display: 'flex',
156          alignItems: 'center',
157          justifyContent: 'center',
158        }}
159      >
160        Hello World
161      </div>
162    ),
163    { ...size }
164  )
165}
166```
167 
168## Dynamic OG Image
169 
170```tsx
171// app/blog/[slug]/opengraph-image.tsx
172import { ImageResponse } from 'next/og'
173 
174export const alt = 'Blog Post'
175export const size = { width: 1200, height: 630 }
176export const contentType = 'image/png'
177 
178type Props = { params: Promise<{ slug: string }> }
179 
180export default async function Image({ params }: Props) {
181  const { slug } = await params
182  const post = await getPost(slug)
183 
184  return new ImageResponse(
185    (
186      <div
187        style={{
188          fontSize: 48,
189          background: 'linear-gradient(to bottom, #1a1a1a, #333)',
190          color: 'white',
191          width: '100%',
192          height: '100%',
193          display: 'flex',
194          flexDirection: 'column',
195          alignItems: 'center',
196          justifyContent: 'center',
197          padding: 48,
198        }}
199      >
200        <div style={{ fontSize: 64, fontWeight: 'bold' }}>{post.title}</div>
201        <div style={{ marginTop: 24, opacity: 0.8 }}>{post.description}</div>
202      </div>
203    ),
204    { ...size }
205  )
206}
207```
208 
209## Custom Fonts
210 
211```tsx
212import { ImageResponse } from 'next/og'
213import { join } from 'path'
214import { readFile } from 'fs/promises'
215 
216export default async function Image() {
217  const fontPath = join(process.cwd(), 'assets/fonts/Inter-Bold.ttf')
218  const fontData = await readFile(fontPath)
219 
220  return new ImageResponse(
221    (
222      <div style={{ fontFamily: 'Inter', fontSize: 64 }}>
223        Custom Font Text
224      </div>
225    ),
226    {
227      width: 1200,
228      height: 630,
229      fonts: [{ name: 'Inter', data: fontData, style: 'normal' }],
230    }
231  )
232}
233```
234 
235## File Naming
236 
237- `opengraph-image.tsx` - Open Graph (Facebook, LinkedIn)
238- `twitter-image.tsx` - Twitter/X cards (optional, falls back to OG)
239 
240## Styling Notes
241 
242ImageResponse uses Flexbox layout:
243- Use `display: 'flex'`
244- No CSS Grid support
245- Styles must be inline objects
246 
247## Multiple OG Images
248 
249Use `generateImageMetadata` for multiple images per route:
250 
251```tsx
252// app/blog/[slug]/opengraph-image.tsx
253import { ImageResponse } from 'next/og'
254 
255export async function generateImageMetadata({ params }) {
256  const images = await getPostImages(params.slug)
257  return images.map((img, idx) => ({
258    id: idx,
259    alt: img.alt,
260    size: { width: 1200, height: 630 },
261    contentType: 'image/png',
262  }))
263}
264 
265export default async function Image({ params, id }) {
266  const images = await getPostImages(params.slug)
267  const image = images[id]
268  return new ImageResponse(/* ... */)
269}
270```
271 
272## Multiple Sitemaps
273 
274Use `generateSitemaps` for large sites:
275 
276```tsx
277// app/sitemap.ts
278import type { MetadataRoute } from 'next'
279 
280export async function generateSitemaps() {
281  // Return array of sitemap IDs
282  return [{ id: 0 }, { id: 1 }, { id: 2 }]
283}
284 
285export default async function sitemap({
286  id,
287}: {
288  id: number
289}): Promise<MetadataRoute.Sitemap> {
290  const start = id * 50000
291  const end = start + 50000
292  const products = await getProducts(start, end)
293 
294  return products.map((product) => ({
295    url: `https://example.com/product/${product.id}`,
296    lastModified: product.updatedAt,
297  }))
298}
299```
300 
301Generates `/sitemap/0.xml`, `/sitemap/1.xml`, etc.
302