Next SEO v7.0.0 Release Notes

🚨 Important Notice

Next SEO v7 is a complete rewrite with breaking changes throughout the entire API.

We strongly recommend staying on v6 unless you:

Need the new JSON-LD components based on Google's latest specifications
Are starting a new project and want to use the latest architecture
Are willing to completely rewrite your SEO implementation

Version 6 will continue to receive bug fixes and security updates.

📋 Summary

Next SEO v7 represents a ground-up rewrite of the library, modernizing every aspect from tooling to API design. This release focuses on:

Modern developer experience with improved TypeScript support and better tree-shaking
AI-friendly development making it easier to maintain and contribute
Google-specification compliance for all JSON-LD components
Maintains Pages Router support with function-based API

🎯 Why v7?

The web development ecosystem has evolved significantly as well as my skills (I hope) since Next SEO's inception. Version 7 addresses several key challenges:

Maintainability: The previous architecture made it difficult to add new components and keep up with Google's evolving structured data specifications
Modern Tooling: Moving from legacy build tools to modern alternatives for better performance and developer experience
AI-Assisted Development: Set up to be AI agent-friendly, making it easier for contributors to add features and fix bugs
Specification Compliance: All JSON-LD components rebuilt from scratch following Google's latest documentation and also you can easily create your own

✨ Major Improvements

1. Modern Build Tooling

tsup replaces microbundle for faster, more reliable builds
Vitest replaces Jest for lightning-fast unit tests
Playwright replaces Cypress for more stable E2E testing
ESM-first with CommonJS compatibility

2. Enhanced Developer Experience

Full TypeScript rewrite with improved type inference
Better tree-shaking support
Comprehensive documentation for each component
AI-friendly codebase with AGENTS.md and ADDING_NEW_COMPONENTS.md guides

3. Google-Compliant JSON-LD Components

All JSON-LD components have been rebuilt from scratch following Google's structured data gallery specifications:

More accurate schema implementation
Better validation and error messages
Support for latest schema.org properties

4. Simplified Pages Router API

Instead of components that manage Next.js internals, v7 exposes pure functions that you control:

// v6 (old)
import { NextSeo } from "next-seo";
<NextSeo title="My Page" description="..." />;

// v7 (new)
import Head from "next/head";
import { generateNextSeo } from "next-seo/pages";
<Head>{generateNextSeo({ title: "My Page", description: "..." })}</Head>;

💔 Breaking Changes

Complete API Redesign

This is not a drop-in replacement. Every aspect of the API has changed:

Pages Router Changes

Feature	v6	v7
Component	`<NextSeo />`	`generateNextSeo()` function
Default SEO	`<DefaultSeo />`	`generateDefaultSeo()` function
Import	`next-seo`	`next-seo/pages`
Usage	Direct component	Wrap in `<Head>`

App Router Changes

Feature	v6	v7
Usage	Components with `useAppDir={true}`	Direct component usage
Title prop	Not required	Built-in support
Placement	page.js	page.tsx/jsx

JSON-LD Component Changes

All components have completely new APIs. Properties have been renamed, restructured, or removed to match Google's specifications.

🔄 Migration Guide

Basic Pages Router Migration

Before (v6):

// pages/index.tsx
import { NextSeo } from "next-seo";

export default function Home() {
  return (
    <>
      <NextSeo
        title="My Homepage"
        description="Welcome to my website"
        canonical="https://example.com"
        openGraph={{
          url: "https://example.com",
          title: "My Homepage",
          description: "Welcome to my website",
        }}
      />
      <h1>Welcome</h1>
    </>
  );
}

After (v7):

// pages/index.tsx
import Head from "next/head";
import { generateNextSeo } from "next-seo/pages";

export default function Home() {
  return (
    <>
      <Head>
        {generateNextSeo({
          title: "My Homepage",
          description: "Welcome to my website",
          canonical: "https://example.com",
          openGraph: {
            url: "https://example.com",
            title: "My Homepage",
            description: "Welcome to my website",
          },
        })}
      </Head>
      <h1>Welcome</h1>
    </>
  );
}

JSON-LD Migration Example

Before (v6):

import { ArticleJsonLd } from "next-seo";

<ArticleJsonLd
  url="https://example.com/article"
  title="Article headline"
  images={["https://example.com/image.jpg"]}
  datePublished="2024-01-01"
  authorName="John Doe"
  publisherName="Example News"
  publisherLogo="https://example.com/logo.jpg"
  description="Article description"
/>;

After (v7):

import { ArticleJsonLd } from "next-seo";

<ArticleJsonLd
  url="https://example.com/article"
  headline="Article headline" // Changed from 'title'
  image="https://example.com/image.jpg" // Changed from 'images'
  datePublished="2024-01-01T00:00:00.000Z" // ISO 8601 format recommended
  author="John Doe" // Changed from 'authorName'
  publisher={{
    // Now an object instead of separate props
    "@type": "Organization",
    name: "Example News",
    logo: "https://example.com/logo.jpg",
  }}
  description="Article description"
/>;

🛠️ Technical Improvements

Build System

tsup: Modern bundler with better ESM/CJS dual package support
Path aliases: Cleaner imports with ~ mapping to src
Optimized output: Smaller bundle sizes with better tree-shaking

Testing Infrastructure

Vitest: 10x faster test execution
Playwright: More reliable E2E tests
React Testing Library: Better integration testing

Developer Tooling

AI-Friendly Documentation: CLAUDE.md and ADDING_NEW_COMPONENTS.md for AI-assisted development
Modern ESLint: Flat config with latest rules
Prettier Integration: Consistent code formatting
Husky: Pre-commit hooks for quality assurance

📚 Documentation

The documentation has been completely rewritten:

Component-by-component guides with examples
Best practices for each component
Migration guides for common scenarios
AI-friendly contribution guides

🤝 Contributing

Version 7 makes contributing easier than ever:

AI agent-friendly codebase
Comprehensive guide for adding new components
Modern tooling that's familiar to developers
Clear patterns and conventions

🔮 Future Plans

Continue v6 maintenance with bug fixes and security updates
Add more JSON-LD components based on community needs
Further performance optimizations

📞 Support

Issues: GitHub Issues
Discussions: GitHub Discussions
v6 Documentation: Available on the master branch
v7 Documentation: Available on the main branch

⚠️ Final Recommendation

Unless you specifically need the new JSON-LD components or are starting a fresh project, we recommend staying on v6. The API changes are extensive and will require a complete rewrite of your SEO implementation. Version 6 remains stable, battle-tested, and will continue to receive maintenance updates.

Thank you for your continued support of Next SEO. I'm excited about the future of SEO in Next.js applications!

garmeeh/next-seo v7.0.0 on GitHub

Next SEO v7.0.0 Release Notes

🚨 Important Notice

📋 Summary

🎯 Why v7?

✨ Major Improvements

1. Modern Build Tooling

2. Enhanced Developer Experience

3. Google-Compliant JSON-LD Components

4. Simplified Pages Router API

💔 Breaking Changes

Complete API Redesign

Pages Router Changes

App Router Changes

JSON-LD Component Changes

🔄 Migration Guide

Basic Pages Router Migration

Before (v6):

After (v7):

JSON-LD Migration Example

Before (v6):

After (v7):

🛠️ Technical Improvements

Build System

Testing Infrastructure

Developer Tooling

📚 Documentation

🤝 Contributing

🔮 Future Plans

📞 Support

⚠️ Final Recommendation

garmeeh/next-seo v7.0.0
on GitHub