Package Exports

nextjs-jsonld-schema

Readme

nextjs-jsonld-schema

Type-safe JSON-LD structured data builders for Next.js. Generate SEO-optimized schema.org markup for calculators, blogs, FAQs, and more.

Features

🎯 Type-safe - Full TypeScript support with detailed interfaces
🚀 Next.js optimized - Works with App Router and Pages Router
📊 Rich snippets ready - Generates Google-compliant structured data
🧩 Modular - Use only what you need
🪶 Lightweight - Zero dependencies (except React peer dep)

Installation

npm install nextjs-jsonld-schema
# or
yarn add nextjs-jsonld-schema
# or
pnpm add nextjs-jsonld-schema

Quick Start

1. Website Schema (Layout)

Add to your root layout for site-wide organization and website schema:

// app/layout.tsx
import { SchemaScript, buildWebsiteSchema } from 'nextjs-jsonld-schema';

export default function RootLayout({ children }) {
  const schema = buildWebsiteSchema({
    siteUrl: "https://example.com",
    siteName: "My Calculator Site",
    description: "Free online calculators for finance, math, and more",
    organization: {
      name: "My Company",
      url: "https://example.com",
      logo: "/logo.png",
      contactEmail: "hello@example.com",
    },
    author: {
      name: "John Doe",
      url: "/about",
      jobTitle: "Lead Developer",
    },
    searchUrlTemplate: "https://example.com/search?q={search_term_string}",
  });

  return (
    <html>
      <head>
        <SchemaScript schema={schema} />
      </head>
      <body>{children}</body>
    </html>
  );
}

2. Calculator/Tool Schema

Perfect for calculator pages, online tools, and web applications:

// app/calculators/loan/page.tsx
import { SchemaScript, buildCalculatorSchema } from 'nextjs-jsonld-schema';

export default function LoanCalculatorPage() {
  const schema = buildCalculatorSchema({
    siteUrl: "https://example.com",
    url: "/calculators/loan",
    title: "Loan Calculator",
    description: "Calculate your monthly loan payments with our free tool",
    category: "FinanceApplication",
    image: "/images/loan-calc.png",
    howtoSteps: [
      { title: "Enter loan amount", description: "Input the total amount you want to borrow" },
      { title: "Set interest rate", description: "Enter the annual interest rate" },
      { title: "Choose term", description: "Select the loan duration in months" },
      { title: "Calculate", description: "Click calculate to see your monthly payment" },
    ],
    faq: [
      { question: "Is this calculator free?", answer: "Yes, completely free to use!" },
      { question: "How accurate is it?", answer: "Our calculator uses standard amortization formulas" },
    ],
    breadcrumbs: [
      { name: "Home", url: "/" },
      { name: "Calculators", url: "/calculators" },
      { name: "Loan Calculator", url: "/calculators/loan" },
    ],
  });

  return (
    <>
      <SchemaScript schema={schema} />
      {/* Your calculator UI */}
    </>
  );
}

3. Blog Post Schema

For blog articles with rich snippet support:

// app/blog/[slug]/page.tsx
import { SchemaScript, buildBlogPostSchema } from 'nextjs-jsonld-schema';

export default function BlogPost({ post }) {
  const schema = buildBlogPostSchema({
    siteUrl: "https://example.com",
    url: `/blog/${post.slug}`,
    title: post.title,
    description: post.excerpt,
    image: post.coverImage,
    publishedAt: post.publishedAt,
    modifiedAt: post.updatedAt,
    author: {
      name: "John Doe",
      url: "/about",
    },
    organization: {
      name: "My Company",
      url: "https://example.com",
      logo: "/logo.png",
    },
    tags: post.tags,
    wordCount: post.wordCount,
    readingTimeMinutes: post.readingTime,
    faq: post.faq,
    breadcrumbs: [
      { name: "Home", url: "/" },
      { name: "Blog", url: "/blog" },
      { name: post.title, url: `/blog/${post.slug}` },
    ],
  });

  return (
    <>
      <SchemaScript schema={schema} />
      <article>{/* Your blog content */}</article>
    </>
  );
}

4. Standalone FAQ Schema

import { SchemaScript, buildFAQSchema } from 'nextjs-jsonld-schema';

const schema = buildFAQSchema({
  items: [
    { question: "What is JSON-LD?", answer: "JSON-LD is a method of encoding Linked Data using JSON" },
    { question: "Why use structured data?", answer: "It helps search engines understand your content better" },
  ],
  url: "https://example.com/faq",
});

<SchemaScript schema={schema} />

import { SchemaScript, buildBreadcrumbSchema } from 'nextjs-jsonld-schema';

const schema = buildBreadcrumbSchema({
  items: [
    { name: "Home", url: "https://example.com" },
    { name: "Products", url: "https://example.com/products" },
    { name: "Calculator", url: "https://example.com/products/calculator" },
  ],
});

<SchemaScript schema={schema} />

API Reference

Builders

Function	Description
`buildWebsiteSchema()`	WebSite + Organization schema
`buildCalculatorSchema()`	SoftwareApplication + HowTo + FAQ
`buildBlogPostSchema()`	BlogPosting + Article schema
`buildFAQSchema()`	Standalone FAQPage schema
`buildBreadcrumbSchema()`	BreadcrumbList schema
`buildProductSchema()`	Product schema

Components

Component	Description
`<SchemaScript />`	Renders single JSON-LD script
`<MultiSchemaScript />`	Renders multiple schemas

Utilities

Function	Description
`toAbsoluteUrl()`	Convert relative URL to absolute
`buildTimeRequired()`	Create ISO 8601 duration
`toISODate()`	Ensure ISO date format
`createSchemaId()`	Create unique schema @id

TypeScript Support

All builders have full TypeScript support with detailed interfaces:

import type { 
  CalculatorSchemaInput, 
  BlogPostSchemaInput,
  FAQItem,
  HowToStep 
} from 'nextjs-jsonld-schema';

Validation

Test your generated schemas with:

Production Usage

This library is used in production at hemenhesap.com - a Turkish financial calculator platform with 100+ calculator pages achieving rich snippets in Google Search.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

Made with ❤️ for the Next.js community