Adding structured data to a Next.js site without losing your mind:

#nextjs #typescript #webdev #seo

Google's rich results look great in search. Getting them? Not so great. I recently added structured data to a Next.js project and learned a few things the hard way.

The problem with JSON-LD

Schema.org documentation is... extensive. Too extensive. You'll find 800+ types and wonder which 3 you actually need.

For most content sites, it's:

Organization (who you are)
WebSite (with SearchAction for sitelinks)
Article or Product (your actual content)
BreadcrumbList (navigation context)

That's it. Ignore the rest until Google tells you otherwise.

Component approach

Instead of dumping JSON-LD strings everywhere, I created typed React components:

// components/seo/ArticleSchema.tsx
export function ArticleSchema({ post }: { post: BlogPost }) {
  const schema = {
    "@context": "https://schema.org",
    "@type": "Article",
    headline: post.title,
    datePublished: post.publishedAt,
    author: {
      "@type": "Person",
      name: post.author.name
    }
  };

  return (
    <script
      type="application/ld+json"
      dangerouslySetInnerHTML={{ __html: JSON.stringify(schema) }}
    />
  );
}

TypeScript catches missing fields before Google does.

The validation loop

Here's the workflow that actually works:

Add schema component to page
Deploy (or use next build && next start)
Test with Google's Rich Results Test
Fix warnings
Repeat

Don't skip step 2. Localhost testing misses URL-related issues.

One gotcha that cost me hours

Dynamic dates in schema must be ISO 8601 format:

// Wrong - breaks validation
datePublished: new Date().toLocaleDateString()

// Right
datePublished: new Date().toISOString()

Google's validator gives cryptic errors for this. Now you know.

Results

After implementing structured data on a small product review site, FAQ rich results started appearing within 2 weeks. No guarantees—Google decides—but eligibility is the first step. The full schema setup took about 4 hours. Most of that was reading documentation I didn't need.

What structured data types are you using? I'm curious if anyone's had luck with HowTo or Recipe schemas.

Top comments (4)

PEACEBINFLOW • Jan 18

Solid post. The “3 schemas you actually need” take is real — most people overbuild this and end up with brittle JSON-LD soup everywhere.

Typed components are the move too. It turns schema from “SEO magic strings” into part of your contract, and TypeScript catching missing fields before Google does is exactly the kind of boring win that saves hours.

Also +1 on the validation loop. People skip the deploy/real URL step and then wonder why Rich Results behaves differently. Google is very much “works on my machine? cool story” 😅

On types: I’ve mostly stuck with Organization/WebSite + Article + BreadcrumbList as the baseline. FAQ can pop, but I’m cautious with anything Google tends to de-prioritize over time. HowTo/Recipe can be great when it’s truly the page’s primary intent — otherwise it feels like you’re just trying to game the SERP and Google usually clocks that.

Elyvora US • Jan 18

Thanks! Yeah, the "JSON-LD soup" phase is something I think every dev goes through at least once 😅

Good point on FAQ — we've had mixed results with it too. Sometimes it pops, sometimes Google just ignores it entirely. The "is this truly the page's intent" filter is solid advice.

And that validation loop catch is so real. Local testing gives you false confidence. The Rich Results tool on a live URL is the only truth.

Appreciate you sharing what's working on your end!