nextjs-jsonld-schema

v1.1.1

Published

3 days ago

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

nextjs-jsonld-schema

Type-safe JSON-LD structured data builders for Next.js. Generate SEO-optimized schema.org markup for calculators, blogs, local businesses, videos, events, 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)
🌍 Multi-language - Built-in support for language-aware templates
⭐ Rating support - AggregateRating for reviews and ratings

📦 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: "[email protected]",
    },
    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",
    useWebApplication: true,      // Use WebApplication instead of SoftwareApplication
    currency: "TRY",              // Currency for offers (default: USD)
    language: "tr-TR",            // Language code
    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" },
    ],
    featureList: ["Real-time calculation", "PDF export", "Mobile friendly"],
    aggregateRating: {
      ratingValue: 4.8,
      ratingCount: 150,
    },
  });

  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. Local Business Schema (NEW in v1.1.0)

For local businesses, stores, restaurants:

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

const schema = buildLocalBusinessSchema({
  siteUrl: "https://example.com",
  url: "/contact",
  name: "My Finance Office",
  description: "Professional financial consulting services",
  type: "FinancialService",
  telephone: "+90 555 123 4567",
  email: "[email protected]",
  address: {
    streetAddress: "123 Main Street",
    addressLocality: "Istanbul",
    addressRegion: "Marmara",
    postalCode: "34000",
    addressCountry: "TR",
  },
  openingHours: ["Mo-Fr 09:00-18:00", "Sa 10:00-14:00"],
  priceRange: "$$",
  geo: {
    latitude: 41.0082,
    longitude: 28.9784,
  },
  sameAs: [
    "https://facebook.com/mycompany",
    "https://twitter.com/mycompany",
    "https://instagram.com/mycompany",
  ],
  aggregateRating: {
    ratingValue: 4.9,
    ratingCount: 85,
  },
});

<SchemaScript schema={schema} />

5. Video Schema (NEW in v1.1.0)

For video content pages:

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

const schema = buildVideoSchema({
  siteUrl: "https://example.com",
  url: "/videos/loan-tutorial",
  name: "How to Calculate Loan Interest",
  description: "Learn the basics of loan interest calculation in this tutorial",
  thumbnailUrl: "/images/video-thumb.jpg",
  uploadDate: "2025-12-24",
  duration: "PT5M30S",  // 5 minutes 30 seconds (ISO 8601)
  embedUrl: "https://www.youtube.com/embed/xxxxx",
  breadcrumbs: [
    { name: "Home", url: "/" },
    { name: "Videos", url: "/videos" },
    { name: "Loan Tutorial", url: "/videos/loan-tutorial" },
  ],
});

<SchemaScript schema={schema} />

6. Event Schema (NEW in v1.1.0)

For events, webinars, conferences:

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

const schema = buildEventSchema({
  siteUrl: "https://example.com",
  url: "/events/finance-webinar",
  name: "Personal Finance Webinar 2025",
  description: "Learn how to manage your personal finances",
  startDate: "2025-12-24T10:00:00+03:00",
  endDate: "2025-12-24T12:00:00+03:00",
  isOnline: true,
  onlineUrl: "https://zoom.us/j/123456789",
  image: "/images/webinar-cover.jpg",
  organizer: {
    name: "Hemen Hesap",
    url: "https://hemenhesap.com",
  },
  offers: [
    {
      price: 0,
      currency: "TRY",
      availability: "InStock",
      validFrom: "2025-12-24",
    },
  ],
  eventStatus: "Scheduled",
  breadcrumbs: [
    { name: "Home", url: "/" },
    { name: "Events", url: "/events" },
    { name: "Finance Webinar", url: "/events/finance-webinar" },
  ],
});

<SchemaScript schema={schema} />

7. 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} />

8. Breadcrumb 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

| Builder | Description | Output Types | |---------|-------------|--------------| | buildWebsiteSchema() | Site-wide schema | Organization, Person, WebSite | | buildCalculatorSchema() | Calculator/tool pages | WebPage, SoftwareApplication/WebApplication, HowTo, FAQ | | buildBlogPostSchema() | Blog articles | WebPage, BlogPosting, FAQ | | buildFAQSchema() | Standalone FAQ | FAQPage | | buildBreadcrumbSchema() | Navigation breadcrumbs | BreadcrumbList | | buildProductSchema() | Product pages | Product, Offer | | buildLocalBusinessSchema() | Local business | LocalBusiness | | buildVideoSchema() | Video content | WebPage, VideoObject | | buildEventSchema() | Events/webinars | Event, Offer |

Components

| Component | Description | |-----------|-------------| | <SchemaScript /> | Single schema injection | | <MultiSchemaScript /> | Multiple schemas injection |

Utilities

| Utility | Description | |---------|-------------| | toAbsoluteUrl() | Convert relative to absolute URL | | buildTimeRequired() | Build ISO 8601 duration (PT5M) | | toISODate() | Convert date to ISO format | | createSchemaId() | Create unique @id reference |

🎯 TypeScript Support

All builders have full TypeScript support with detailed interfaces:

import type { 
  CalculatorSchemaInput, 
  BlogPostSchemaInput, 
  FAQItem, 
  HowToStep,
  AggregateRating,
  LocalBusinessSchemaInput,
  VideoSchemaInput,
  EventSchemaInput,
} 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 150+ pages achieving rich snippets in Google Search.

🆚 Comparison with Alternatives

| Feature | nextjs-jsonld-schema | next-seo | schema-dts | |---------|---------------------|----------|------------| | Type-safe | ✅ | ⚠️ Partial | ✅ | | Next.js optimized | ✅ | ✅ | ❌ | | Calculator/Tool support | ✅ | ❌ | ❌ | | HowTo + FAQ combined | ✅ | ❌ | ❌ | | Multi-language | ✅ | ⚠️ | ❌ | | Zero config | ✅ | ❌ | ❌ | | Bundle size | ~5KB | ~15KB | ~50KB |

📝 Changelog

v1.1.1 (2025-12)

📝 Updated example dates to December 2025

v1.1.0 (2025-12)

✨ Added buildLocalBusinessSchema() for local businesses
✨ Added buildVideoSchema() for video content
✨ Added buildEventSchema() for events and webinars
✨ Added useWebApplication option for WebApplication type
✨ Added currency parameter for localized offers
✨ Added howToTitleTemplate for multi-language HowTo titles
✨ Added aggregateRating support for ratings
✨ Added featureList for application features
✨ Added datePublished to WebPage
🔧 Improved TypeScript types

v1.0.1 (2025-12)

🐛 Bug fixes and improvements

v1.0.0 (2025-12)

🎉 Initial release

🤝 Contributing

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

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

📄 License

Made with ❤️ for the Next.js community

⬆ Back to top

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

nextjs-jsonld-schema

✨ Features

📦 Installation

🚀 Quick Start

1. Website Schema (Layout)

2. Calculator/Tool Schema

3. Blog Post Schema

4. Local Business Schema (NEW in v1.1.0)

5. Video Schema (NEW in v1.1.0)

6. Event Schema (NEW in v1.1.0)

7. Standalone FAQ Schema

8. Breadcrumb Schema

📚 API Reference

Builders

Components

Utilities

🎯 TypeScript Support

✅ Validation

🏭 Production Usage

🆚 Comparison with Alternatives

📝 Changelog

v1.1.1 (2025-12)

v1.1.0 (2025-12)

v1.0.1 (2025-12)

v1.0.0 (2025-12)

🤝 Contributing

📄 License