next-seo

next-seo is a plugin that makes managing SEO in Next.js projects easier by providing a large library of typed React components for Schema.org JSON-LD structured data — articles, products, events, FAQs, recipes, job postings, and dozens more. Rather than hand-writing JSON-LD script tags and keeping their shape valid, developers render a component with plain props and next-seo produces spec-compliant structured data, including a processor system that infers @type fields automatically so simple strings can stand in for full objects.

The library also supports Pages Router usage via a separate next-seo/pages entrypoint for teams not yet on the App Router, and exposes its internal JsonLdScript component plus 60+ processors so consumers can build fully custom Schema.org components that follow the same ergonomic patterns as the built-ins.

What You Get

• 60+ pre-built JSON-LD components covering common Schema.org types (Article, Product, FAQ, Event, Recipe, JobPosting, LocalBusiness, Course, HowTo, and more)
• A processor system that accepts flexible inputs (e.g. a plain string for an author) and expands them into fully-typed Schema.org objects without requiring @type to be specified manually
• The underlying JsonLdScript component and processor utilities exported for building fully custom structured-data components in the same style
• A separate next-seo/pages entrypoint for teams still on the Next.js Pages Router
• Full TypeScript types for every component’s props

Common Use Cases

• Adding Article/BlogPosting JSON-LD to blog posts so they qualify for rich snippets in search results
• Marking up e-commerce product pages with Product and offer structured data for shopping search features
• Adding FAQ or HowTo structured data to support pages to earn expandable rich results
• Marking up job listing pages with JobPosting schema for Google Jobs indexing
• Building a custom Schema.org component for a niche content type using the exported processors and JsonLdScript primitives

Under The Hood

Architecture - The library is organized around a single core primitive, JsonLdScript (src/core/JsonLdScript.tsx), which serializes a data object into a <script type="application/ld+json"> tag; every one of the 60+ components in src/components/ is a thin wrapper that shapes its props into a Schema.org-typed object and hands it to that primitive. A shared src/utils/processors.ts module normalizes flexible inputs (e.g. an author passed as a plain string vs. an object) into fully-typed nested Schema.org objects, so individual components stay declarative and small.

Tech Stack - Written in TypeScript and built with tsup for dual ESM/CJS output with generated .d.ts files; a next-seo/pages subpath export targets the Pages Router separately from the default App Router-oriented entrypoint. The workspace uses pnpm, Vitest for unit tests, and Playwright for end-to-end tests against the included example app.

Code Quality - Every component in src/components/ ships with a co-located .test.tsx file, giving broad unit-test coverage of the processor and serialization logic; ESLint and a typecheck script run as part of pnpm test. Naming is consistent across components (<Type>JsonLd + <Type>JsonLdProps), which keeps the large surface area navigable.

API Design - The @type-optional processor pattern is the standout ergonomic choice: consumers can pass a plain string for author or image instead of a full Schema.org object, and the library expands it correctly, which removes most of the boilerplate that raw JSON-LD authoring requires. Exporting JsonLdScript and the processors publicly also lets teams build fully custom components without forking the library.