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