Frequently Asked Questions

Find answers to the most common questions about generate-metadata.

Setup and Installation

How do I get a DSN?

Do I need to restart my server when changing the DSN?

Yes, environment variables require a server restart to take effect.

Usage Questions

What's the difference between `getMetadata()` and `getRootMetadata()`?

getMetadata(): Use for individual pages (e.g., /about, /blog/[slug])
getRootMetadata(): Use only for root layouts

When should I use `fallback` vs `override`?

fallback: Backup metadata used when the API is unavailable
override: Metadata that always takes priority, regardless of API response

Should I include search parameters in the path?

Yes, if they affect the content or metadata:

// Include relevant search params
const path = `/search?q=${query}&category=${category}`;
 
// Don't include irrelevant params like tracking IDs
const path = `/products/${id}`; // Skip ?utm_source=...

Performance and Caching

How does caching work?

Responses are cached by the path parameter
Cache persists for the lifetime of the client instance
Same path = cached response (no additional API call)
Different paths = separate cache entries

How can I clear the cache?

Create a new client instance:

// This will have a fresh cache
const newClient = new GenerateMetadataClient({ dsn: "..." });

What's the performance impact?

Bundle size: ~15KB gzipped when importing framework-specific adapters
API calls: Cached responses after first request per path
Fallback mode: Zero overhead when API is unavailable

Troubleshooting

My metadata isn't appearing

Check exports: Ensure generateMetadata (Next.js) or head (TanStack Start) are properly exported
Verify DSN: Check your environment variables and restart your server
Inspect HTML: Use browser dev tools to check if meta tags are in the <head>
Console logs: Look for error messages or warnings

API calls are failing

Check DSN: Verify it's correct and active
Network: Ensure you have internet connectivity
Fallback: Your fallback metadata should still be used

TypeScript errors

Import path: Use framework-specific imports (generate-metadata/next or generate-metadata/tanstack-start)
Props typing: Ensure your factory function has correct prop types
Update: Make sure you have the latest version installed

Environment variables not working

File location: Ensure .env files are in the correct location
Restart server: Environment changes require a restart
Prefix: Use NEXT_PUBLIC_ for Next.js, regular names for TanStack Start
Quotes: Don't wrap values in quotes in .env files

Duplicate meta tags

Library deduplication: The library automatically deduplicates meta tags
External sources: Check if other tools are adding meta tags
Framework conflicts: Ensure you're not manually adding the same meta tags elsewhere

Edit this page on GitHub

On this page