Next SEO

Minor Changes

• 7784fd2: Add optional nonce prop to all JSON-LD components for Content Security Policy (CSP) compliance

Sites that send a strict CSP header such as script-src 'nonce-{RANDOM}' block inline scripts without a matching nonce. Every JSON-LD component now accepts an optional nonce prop, which is forwarded to the rendered <script type="application/ld+json"> tag. Omit the prop and no nonce attribute is rendered, so existing usage is unchanged.

  import { headers } from "next/headers";
  import { ArticleJsonLd } from "next-seo";

  const nonce = (await headers()).get("x-nonce") ?? undefined;

  <ArticleJsonLd headline="My Article" nonce={nonce} />;

Outrank

Get traffic and outrank competitors with Backlinks & SEO-optimized content while you sleep! I've been keeping a close eye on this new tool and it seems to be gaining a lot of traction and delivering great results. Try it now!

image

The only SEO skill your agent needs. Install it now

<img alt="SEO Skill banner" src="./seo-skill.png">

Want Next.js news in your inbox each week? Subscribe to Next.js Weekly →

Next SEO

npm

npm version

TypeScript

License

Next SEO is a plugin that makes managing your SEO easier in Next.js projects. It provides components for structured data (JSON-LD) that helps search engines understand your content better.

📋 Table of Contents

_Looking for v6 documentation? View Here_

_Still using <NextSeo /> component in Pages? View docs here [/src/pages/README.md]_

🚀 Quick Start

Installation

npm install next-seo
# or
yarn add next-seo
# or
pnpm add next-seo
# or
bun add next-seo

Basic Usage

import { ArticleJsonLd } from "next-seo";

export default function BlogPost() {
  return (
    <>
      <ArticleJsonLd
        headline="Getting Started with Next SEO"
        datePublished="2024-01-01T08:00:00+00:00"
        author="John Doe"
        image="https://example.com/article-image.jpg"
        description="Learn how to improve your Next.js SEO"
      />
      <article>
        <h1>Getting Started with Next SEO</h1>
        {/* Your content */}
      </article>
    </>
  );
}

Note: For standard meta tags (<meta>, <title>), use Next.js's built-in generateMetadata function.

Pages Router Support: If you're using Next.js Pages Router, import components from next-seo/pages. See the Pages Router documentation for details.

Content Security Policy (CSP)

Every JSON-LD component renders an inline <script type="application/ld+json"> tag. If your site sends a strict CSP header such as script-src 'nonce-{RANDOM}', that inline script is blocked unless it carries a matching nonce.

All JSON-LD components accept an optional nonce prop, which is rendered as the nonce attribute on the script tag:

import { headers } from "next/headers";
import { ArticleJsonLd } from "next-seo";

export default async function BlogPost() {
  const nonce = (await headers()).get("x-nonce") ?? undefined;

  return (
    <ArticleJsonLd
      headline="Getting Started with Next SEO"
      datePublished="2024-01-01T08:00:00+00:00"
      author="John Doe"
      nonce={nonce}
    />
  );
}

The nonce value must be generated per request and match the one in your CSP header. See the Next.js CSP guide for how to generate one in middleware and expose it to your pages.

Note: Omit the nonce prop entirely if you are not using a nonce-based CSP — no attribute is rendered when it is not provided.

Support This Project

Feel like supporting this free plugin?

It takes a lot of time to maintain an open source project so any small contribution is greatly appreciated.

Coffee fuels coding ☕️

<a href="https://www.buymeacoffee.com/garmeeh" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" alt="Buy Me A Coffee" style="height: 60px !important;width: 217px !important;" ></a>

Components

ArticleJsonLd

The ArticleJsonLd component helps you add structured data for articles, blog posts, and news articles to improve their appearance in search results.

Basic Usage

import { ArticleJsonLd } from "next-seo";

export default function ArticlePage() {
  return (
    <>
      <ArticleJsonLd
        headline="My Amazing Article"
        datePublished="2024-01-01T08:00:00+08:00"
        author="John Doe"
        image="https://example.com/article-image.jpg"
        description="This article explains amazing things about Next.js SEO"
      />
      <article>
        <h1>My Amazing Article</h1>
        {/* Article content */}
      </article>
    </>
  );
}

Advanced Example with Multiple Authors

<ArticleJsonLd
  type="NewsArticle"
  headline="Breaking: Next SEO v7 Released"
  url="https://example.com/news/next-seo-v7"
  datePublished="2024-01-01T08:00:00+08:00"
  dateModified="2024-01-02T10:00:00+08:00"
  author={[
    {
      "@type": "Person",
      name: "Jane Smith",
      url: "https://example.com/authors/jane",
    },
    "John Doe", // Can mix objects and strings
  ]}
  image={[
    "https://example.com/images/16x9.jpg",
    "https://example.com/images/4x3.jpg",
    "https://example.com/images/1x1.jpg",
  ]}
  publisher={{
    "@type": "Organization",
    name: "Example News",
    logo: "https://example.com/logo.png",
  }}
  isAccessibleForFree={true}
/>

Blog Posting Example

<ArticleJsonLd
  type="BlogPosting"
  headline="10 Tips for Better SEO"
  url="https://example.com/blog/seo-tips"
  datePublished="2024-01-01T08:00:00+08:00"
  author={{
    "@type": "Organization",
    name: "SEO Experts Inc.",
    url: "https://example.com",
  }}
  image={{
    "@type": "ImageObject",
    url: "https://example.com/blog-hero.jpg",
    width: 1200,
    height: 630,
    caption: "SEO Tips Illustration",
  }}
  description="Learn the top 10 tips to improve your website's SEO"
  mainEntityOfPage={{
    "@type": "WebPage",
    "@id": "https://example.com/blog/seo-tips",
  }}
/>

Props

| Property | Type | Description |

| --------------------- | ------------------------------------------------------- | -------------------------------------------------------- |

| type | "Article" \| "NewsArticle" \| "BlogPosting" \| "Blog" | The type of article. Defaults to "Article" |

| headline | string | Required. The headline of the article |

| url | string | The canonical URL of the article |

| author | string \| Person \| Organization \| Author[] | The author(s) of the article |

| datePublished | string | ISO 8601 date when the article was published |

| dateModified | string | ISO 8601 date when the article was last modified |

| image | string \| ImageObject \| (string \| ImageObject)[] | Article images. Google recommends multiple aspect ratios |

| publisher | Organization | The publisher of the article |

| description | string | A short description of the article |

| isAccessibleForFree | boolean | Whether the article is accessible for free |

| mainEntityOfPage | string \| WebPage | Indicates the article is the primary content of the page |

| scriptId | string | Custom ID for the script tag |

| scriptKey | string | Custom key prop for React |

| nonce | string | CSP nonce for the script tag |

Best Practices

1. Always include images: Google strongly recommends including high-resolution images with multiple aspect ratios (16x9, 4x3, 1x1)
2. Use ISO 8601 dates: Include timezone information for accuracy
3. Multiple authors: List all authors when applicable
4. Publisher logo: Include a logo for NewsArticle type
5. Update dateModified: Keep this current when updating content

↑ Back to Components

ClaimReviewJsonLd

The ClaimReviewJsonLd component helps you add structured data for fact-checking articles that review claims made by others. This enables a summarized version of your fact check to display in Google Search results.

Basic Usage

import { ClaimReviewJsonLd } from "next-seo";

export default function FactCheckPage() {
  return (
    <>
      <ClaimReviewJsonLd
        claimReviewed="The world is flat"
        reviewRating={{
          ratingValue: 1,
          bestRating: 5,
          worstRating: 1,
          alternateName: "False",
        }}
        url="https://example.com/fact-check/flat-earth"
        author="Fact Check Team"
      />
      <article>
        <h1>Fact Check: The World is Flat</h1>
        {/* Your fact check content */}
      </article>
    </>
  );
}

Props

| Property | Type | Description |

| --------------- | ---------------------------------- | ------------------------------------------------------------------------------------- |

| claimReviewed | string | Required. A short summary of the claim being evaluated (keep under 75 characters) |

| reviewRating | object | Required. The assessment of the claim with rating value and textual rating |

| url | string | Required. Link to the page hosting the full fact check article |

| author | string \| Organization \| Person | The publisher of the fact check article |

| itemReviewed | Claim | Detailed information about the claim being reviewed |

| scriptId | string | Custom ID for the script tag |

| scriptKey | string | Custom key for script identification |

| nonce | string | CSP nonce for the script tag |

Review Rating Properties

| Property | Type | Description |

| --------------- | -------- | ------------------------------------------------------------------------------------------- |

| alternateName | string | Required. The truthfulness rating as human-readable text (e.g., "False", "Mostly true") |

| ratingValue | number | Required. Numeric rating (closer to bestRating = more true) |

| bestRating | number | Best value in the rating scale (must be greater than worstRating) |

| worstRating | number | Worst value in the rating scale (minimum value of 1) |

| name | string | Alternative to alternateName (use alternateName instead) |

Advanced Example with Claim Details

<ClaimReviewJsonLd
  claimReviewed="Climate change is not real"
  reviewRating={{
    ratingValue: 1,
    bestRating: 5,
    worstRating: 1,
    alternateName: "Pants on Fire",
  }}
  url="https://example.com/fact-check/climate-denial"
  author={{
    name: "Climate Facts Organization",
    url: "https://example.com",
    logo: "https://example.com/logo.jpg",
  }}
  itemReviewed={{
    author: {
      name: "Climate Denial Institute",
      sameAs: "https://climatedenial.example.com",
    },
    datePublished: "2024-06-20",
    appearance: {
      url: "https://example.com/original-claim",
      headline: "The Great Climate Hoax",
      datePublished: "2024-06-22",
      author: "John Doe",
      publisher: {
        name: "Denial News",
        logo: "https://example.com/denial-logo.jpg",
      },
    },
  }}
/>

Best Practices

1. Clear ratings: Use descriptive alternateName values that clearly indicate the verdict
2. Claim summary: Keep claimReviewed concise (under 75 characters) to prevent wrapping
3. Full context: Include itemReviewed when possible to provide claim origin details
4. Consistent scale: Use a consistent rating scale across all your fact checks
5. Author credibility: Clearly identify your fact-checking organization

↑ Back to Components

CreativeWorkJsonLd

The CreativeWorkJsonLd component helps you add structured data for various types of creative content, with special support for marking paywalled or subscription-based content. This enables Google to differentiate paywalled content from cloaking practices.

Basic Usage

import { CreativeWorkJsonLd } from "next-seo";

export default function ArticlePage() {
  return (
    <>
      <CreativeWorkJsonLd
        type="Article"
        headline="Premium Article"
        datePublished="2024-01-01T08:00:00+08:00"
        author="John Doe"
        description="This premium article requires a s