Skip to content

ever-co/ever-works / .agents/skills/next-best-practices

next-best-practices

Verified

Next.js best practices - file conventions, RSC boundaries, data patterns, async APIs, metadata, error handling, route handlers, image/font optimization, bundling

FileKindSize
SKILL.mdskill md3.9 KB
async-patterns.mdmarkdown1.6 KB
bundling.mdmarkdown4.6 KB
data-patterns.mdmarkdown6.6 KB
debug-tricks.mdmarkdown2.9 KB
directives.mdmarkdown1.4 KB
error-handling.mdmarkdown4.6 KB
file-conventions.mdmarkdown3.7 KB
font.mdmarkdown5.0 KB
functions.mdmarkdown5.8 KB
hydration-error.mdmarkdown1.7 KB
image.mdmarkdown3.8 KB
metadata.mdmarkdown7.1 KB
parallel-routes.mdmarkdown7.1 KB
route-handlers.mdmarkdown3.3 KB
rsc-boundaries.mdmarkdown4.6 KB
runtime-selection.mdmarkdown986 B
scripts.mdmarkdown3.6 KB
self-hosting.mdmarkdown8.5 KB
suspense-boundaries.mdmarkdown1.4 KB

metadata.md

View on GitHub
# Metadata

Add SEO metadata to Next.js pages using the Metadata API.

## Important: Server Components Only

The `metadata` object and `generateMetadata` function are **only supported in Server Components**. They cannot be used in Client Components.

If the target page has `'use client'`:

1. Remove `'use client'` if possible, move client logic to child components
2. Or extract metadata to a parent Server Component layout
3. Or split the file: Server Component with metadata imports Client Components

## Static Metadata

```tsx
import type { Metadata } from 'next';

export const metadata: Metadata = {
	title: 'Page Title',
	description: 'Page description for search engines'
};
```

## Dynamic Metadata

```tsx
import type { Metadata } from 'next';

type Props = { params: Promise<{ slug: string }> };

export async function generateMetadata({ params }: Props): Promise<Metadata> {
	const { slug } = await params;
	const post = await getPost(slug);
	return { title: post.title, description: post.description };
}
```

## Avoid Duplicate Fetches

Use React `cache()` when the same data is needed for both metadata and page:

```tsx
import { cache } from 'react';

export const getPost = cache(async (slug: string) => {
	return await db.posts.findFirst({ where: { slug } });
});
```

## Viewport

Separate from metadata for streaming support:

```tsx
import type { Viewport } from 'next';

export const viewport: Viewport = {
	width: 'device-width',
	initialScale: 1,
	themeColor: '#000000'
};

// Or dynamic
export function generateViewport({ params }): Viewport {
	return { themeColor: getThemeColor(params) };
}
```

## Title Templates

In root layout for consistent naming:

```tsx
export const metadata: Metadata = {
	title: { default: 'Site Name', template: '%s | Site Name' }
};
```

## Metadata File Conventions

Reference: https://nextjs.org/docs/app/getting-started/project-structure#metadata-file-conventions

Place these files in `app/` work (or route segments):

| File                            | Purpose                                       |
| ------------------------------- | --------------------------------------------- |
| `favicon.ico`                   | Favicon                                       |
| `icon.png` / `icon.svg`         | App icon                                      |
| `apple-icon.png`                | Apple app icon                                |
| `opengraph-image.png`           | OG image                                      |
| `twitter-image.png`             | Twitter card image                            |
| `sitemap.ts` / `sitemap.xml`    | Sitemap (use `generateSitemaps` for multiple) |
| `robots.ts` / `robots.txt`      | Robots directives                             |
| `manifest.ts` / `manifest.json` | Web app manifest                              |

## SEO Best Practice: Static Files Are Often Enough

For most sites, **static metadata files provide excellent SEO coverage**:

```
app/
├── favicon.ico
├── opengraph-image.png     # Works for both OG and Twitter
├── sitemap.ts
├── robots.ts
└── layout.tsx              # With title/description metadata
```

**Tips:**

- A single `opengraph-image.png` covers both Open Graph and Twitter (Twitter falls back to OG)
- Static `title` and `description` in layout metadata is sufficient for most pages
- Only use dynamic `generateMetadata` when content varies per page

---

# OG Image Generation

Generate dynamic Open Graph images using `next/og`.

## Important Rules

1. **Use `next/og`** - not `@vercel/og` (it's built into Next.js)
2. **No searchParams** - OG images can't access search params, use route params instead
3. **Avoid Edge runtime** - Use default Node.js runtime

```tsx
// Good
import { ImageResponse } from 'next/og';

// Bad
// import { ImageResponse } from '@vercel/og'
// export const runtime = 'edge'
```

## Basic OG Image

```tsx
// app/opengraph-image.tsx
import { ImageResponse } from 'next/og';

export const alt = 'Site Name';
export const size = { width: 1200, height: 630 };
export const contentType = 'image/png';

export default function Image() {
	return new ImageResponse(
		<div
			style={{
				fontSize: 128,
				background: 'white',
				width: '100%',
				height: '100%',
				display: 'flex',
				alignItems: 'center',
				justifyContent: 'center'
			}}
		>
			Hello World
		</div>,
		{ ...size }
	);
}
```

## Dynamic OG Image

```tsx
// app/blog/[slug]/opengraph-image.tsx
import { ImageResponse } from 'next/og';

export const alt = 'Blog Post';
export const size = { width: 1200, height: 630 };
export const contentType = 'image/png';

type Props = { params: Promise<{ slug: string }> };

export default async function Image({ params }: Props) {
	const { slug } = await params;
	const post = await getPost(slug);

	return new ImageResponse(
		<div
			style={{
				fontSize: 48,
				background: 'linear-gradient(to bottom, #1a1a1a, #333)',
				color: 'white',
				width: '100%',
				height: '100%',
				display: 'flex',
				flexDirection: 'column',
				alignItems: 'center',
				justifyContent: 'center',
				padding: 48
			}}
		>
			<div style={{ fontSize: 64, fontWeight: 'bold' }}>{post.title}</div>
			<div style={{ marginTop: 24, opacity: 0.8 }}>{post.description}</div>
		</div>,
		{ ...size }
	);
}
```

## Custom Fonts

```tsx
import { ImageResponse } from 'next/og';
import { join } from 'path';
import { readFile } from 'fs/promises';

export default async function Image() {
	const fontPath = join(process.cwd(), 'assets/fonts/Inter-Bold.ttf');
	const fontData = await readFile(fontPath);

	return new ImageResponse(<div style={{ fontFamily: 'Inter', fontSize: 64 }}>Custom Font Text</div>, {
		width: 1200,
		height: 630,
		fonts: [{ name: 'Inter', data: fontData, style: 'normal' }]
	});
}
```

## File Naming

- `opengraph-image.tsx` - Open Graph (Facebook, LinkedIn)
- `twitter-image.tsx` - Twitter/X cards (optional, falls back to OG)

## Styling Notes

ImageResponse uses Flexbox layout:

- Use `display: 'flex'`
- No CSS Grid support
- Styles must be inline objects

## Multiple OG Images

Use `generateImageMetadata` for multiple images per route:

```tsx
// app/blog/[slug]/opengraph-image.tsx
import { ImageResponse } from 'next/og';

export async function generateImageMetadata({ params }) {
	const images = await getPostImages(params.slug);
	return images.map((img, idx) => ({
		id: idx,
		alt: img.alt,
		size: { width: 1200, height: 630 },
		contentType: 'image/png'
	}));
}

export default async function Image({ params, id }) {
	const images = await getPostImages(params.slug);
	const image = images[id];
	return new ImageResponse(/* ... */);
}
```

## Multiple Sitemaps

Use `generateSitemaps` for large sites:

```tsx
// app/sitemap.ts
import type { MetadataRoute } from 'next';

export async function generateSitemaps() {
	// Return array of sitemap IDs
	return [{ id: 0 }, { id: 1 }, { id: 2 }];
}

export default async function sitemap({ id }: { id: number }): Promise<MetadataRoute.Sitemap> {
	const start = id * 50000;
	const end = start + 50000;
	const products = await getProducts(start, end);

	return products.map((product) => ({
		url: `https://example.com/product/${product.id}`,
		lastModified: product.updatedAt
	}));
}
```

Generates `/sitemap/0.xml`, `/sitemap/1.xml`, etc.
receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 322kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 322kUpdated Claude CodeCodexVerifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 322kUpdated Claude CodeCodexVerifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 322kUpdated Claude CodeCodexVerifiedInstall