SEO Meta Tags

SEO Meta Tags

Boilerplate and component library for production-ready metadata across three framework targets.

Decision Tree

Determine the correct framework path first:

1. Static HTML site or any-backend project — Read references/​html.md
2. Next.js 13+ App Router — Read references/​nextjs.md
3. Vite + React — Read references/​vite.md, React section
4. Vite + Vue 3 — Read references/​vite.md, Vue section
5. Multiple frameworks at once — Read all relevant reference files

Then determine action type:

• Creating metadata from scratch? — Read matching reference → copy boilerplate → replace placeholders.
• Updating existing metadata? — Load file → keep structure → change requested values → verify parity across tag families.
• Auditing / reviewing metadata? — Run through Quality Gate below → report issues.
• Migrating between frameworks? — Read source reference → read target reference → map fields.

Framework Selection

Read only the reference file that matches the user's target framework.

Metadata Families

Every framework target must keep parity across these families. When modifying one family, verify the others remain consistent.

1. Essential / Primary

2. Open Graph (og:*)

For article type also include: article:published_time, article:modified_time, article:author, article:tag.

3. Twitter Cards (twitter:*)

4. Theme Color

Provide three values:

• Default: <meta name="theme-color" content="..."> or single value
• Light: media="(prefers-color-scheme: light)"
• Dark: media="(prefers-color-scheme: dark)"

Next.js uses the themeColor array in the Metadata object.

5. Icons and Manifest

Generate with favicon.io or RealFaviconGenerator.

6. Structured Data (JSON-LD)

Emit a <script type="application/​ld+json"> block (HTML/​Vite) or use a separate Script component in Next.js. Required keys:

{
	"@context": "https://schema.org",
	"@type": "WebSite",
	"name": "",
	"description": "",
	"url": "",
	"image": { "@type": "ImageObject", "url": "", "width": 1200, "height": 630 },
	"author": { "@type": "Person", "name": "" },
	"publisher": {
		"@type": "Organization",
		"name": "",
		"logo": { "@type": "ImageObject", "url": "" }
	}
}

Common @type values: WebSite, Article, Organization, Product, FAQPage, BreadcrumbList.

7. Internationalization (hreflang)

<link rel="alternate" hreflang="en" href="https://example.com/​en/" />
<link rel="alternate" hreflang="es" href="https://example.com/​es/" />
<link rel="alternate" hreflang="x-default" href="https://example.com/" />

Next.js equivalent: alternates.languages in the Metadata object.

8. Performance Hints

Include when external resources are used:

<link rel="preconnect" href="https://fonts.googleapis.com" />
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
<link rel="dns-prefetch" href="https://www.google-analytics.com" />

Placeholder Tokens

All boilerplate files use {{PLACEHOLDER_NAME}} tokens. Common tokens:

When implementing for a user, replace every {{...}} token. Never leave placeholders in production output.

Quality Gate

Run these checks before considering any metadata task complete:

1. No placeholders — grep for {{ in all modified files; count must be zero.
2. Absolute URLs — canonical, OG url, OG image, Twitter image, JSON-LD url/​image must start with https://.
3. Image alt text — every og:image / twitter:image must have a corresponding alt field.
4. No duplicate tags — no two conflicting <title>, description, or canonical tags in the same scope.
5. Title length — verify under 60 characters.
6. Description length — verify 150-160 characters.
7. JSON-LD validity — valid JSON with required @context and @type keys.
8. OG/​Twitter parity — if OG title is set, Twitter title should also be set (and vice versa).
9. Canonical consistency — canonical URL matches the actual page URL or intended redirect target.
10. Theme color — includes both light and dark media variants.
11. hreflang — includes x-default when language alternates exist.
12. Robots — allows indexing unless user explicitly requests noindex.

Image Specifications

Testing Tools

Recommend to users after deployment:

• Facebook Sharing Debugger
• Twitter Card Validator
• LinkedIn Post Inspector
• Open Graph Check
• Schema Markup Validator
• Google Rich Results Test

Common Mistakes

Migration Paths