DEV Community: Alamin Sarker

How to Build a Provider-Agnostic AI SEO Pipeline in Next.js

Alamin Sarker — Sun, 19 Apr 2026 05:14:34 +0000

I spent an entire sprint ripping out OpenAI calls from a client's Next.js app because they wanted to switch to Anthropic. Every metadata generator, every schema builder, every keyword cluster — all tightly coupled to one SDK. Three days of refactoring for what should have been a config change.

That experience turned into an obsession: build an AI SEO tool pipeline that treats the model as a swappable dependency, not the foundation. In this article I'll show you the exact pattern — a provider-agnostic adapter layer in Next.js that generates SEO metadata, structured schema, and keyword suggestions without locking you into any single vendor.

The Problem with Most AI SEO Integrations

Most tutorials go straight to openai.chat.completions.create(...) inside a Route Handler and call it done. That works until:

Your client wants to use their own API key on a different provider
OpenAI raises prices and Gemini Flash is suddenly 10x cheaper
You want to A/B test output quality across models

The fix isn't clever prompt engineering. It's architecture.

Here's the pattern: define a SeoProvider interface, implement it for each vendor, and inject the right one at runtime via an environment variable. Your Next.js App Router handlers never import a specific SDK — they only talk to the interface.

Step 1: Define the Provider Interface

Create a shared type that all providers must satisfy:

// lib/seo/types.ts

export interface SeoInput {
  url: string;
  pageContent: string;
  targetKeyword?: string;
}

export interface SeoOutput {
  title: string;
  description: string;
  keywords: string[];
  schema: Record<string, unknown>;
}

export interface SeoProvider {
  generate(input: SeoInput): Promise<SeoOutput>;
}

That's your contract. Nothing else in the app needs to know which model is running.

Step 2: Implement Concrete Adapters

Now write one adapter per provider. They all implement the same interface:

// lib/seo/providers/openai.ts
import OpenAI from "openai";
import { SeoProvider, SeoInput, SeoOutput } from "../types";

export class OpenAIProvider implements SeoProvider {
  private client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

  async generate(input: SeoInput): Promise<SeoOutput> {
    const prompt = buildPrompt(input); // shared prompt builder (see below)

    const res = await this.client.chat.completions.create({
      model: "gpt-4o-mini",
      messages: [{ role: "user", content: prompt }],
      response_format: { type: "json_object" },
    });

    return JSON.parse(res.choices[0].message.content ?? "{}");
  }
}

// lib/seo/providers/anthropic.ts
import Anthropic from "@anthropic-ai/sdk";
import { SeoProvider, SeoInput, SeoOutput } from "../types";

export class AnthropicProvider implements SeoProvider {
  private client = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });

  async generate(input: SeoInput): Promise<SeoOutput> {
    const prompt = buildPrompt(input);

    const res = await this.client.messages.create({
      model: "claude-3-5-haiku-20241022",
      max_tokens: 1024,
      messages: [{ role: "user", content: prompt }],
    });

    const text = res.content[0].type === "text" ? res.content[0].text : "";
    return JSON.parse(text);
  }
}

Both use the same buildPrompt function:

// lib/seo/prompt.ts
import { SeoInput } from "./types";

export function buildPrompt(input: SeoInput): string {
  return `
    Analyze the following web page content and return a JSON object with these fields:
    - title: SEO-optimized page title (50-60 chars)
    - description: meta description (150-160 chars)
    - keywords: array of 8-10 relevant keywords
    - schema: a JSON-LD Article schema object

    Target keyword: ${input.targetKeyword ?? "none specified"}
    URL: ${input.url}

    Page content:
    ${input.pageContent.slice(0, 3000)}

    Return ONLY valid JSON. No markdown, no explanation.
  `;
}

The prompt is provider-agnostic — the same text goes to any model.

Step 3: The Provider Factory + Route Handler

Wire everything together with a factory function and a single API route:

// lib/seo/factory.ts
import { SeoProvider } from "./types";
import { OpenAIProvider } from "./providers/openai";
import { AnthropicProvider } from "./providers/anthropic";

export function getSeoProvider(): SeoProvider {
  const provider = process.env.SEO_AI_PROVIDER ?? "openai";

  switch (provider) {
    case "anthropic":
      return new AnthropicProvider();
    case "openai":
    default:
      return new OpenAIProvider();
  }
}

// app/api/seo/route.ts
import { NextRequest, NextResponse } from "next/server";
import { getSeoProvider } from "@/lib/seo/factory";

export async function POST(req: NextRequest) {
  const body = await req.json();
  const { url, pageContent, targetKeyword } = body;

  if (!url || !pageContent) {
    return NextResponse.json({ error: "Missing required fields" }, { status: 400 });
  }

  try {
    const provider = getSeoProvider();
    const result = await provider.generate({ url, pageContent, targetKeyword });
    return NextResponse.json(result);
  } catch (err) {
    console.error("[SEO Pipeline Error]", err);
    return NextResponse.json({ error: "Generation failed" }, { status: 500 });
  }
}

Switch providers by changing one env var:

# .env.local
SEO_AI_PROVIDER=anthropic   # or "openai", or whatever you add next

No code changes. No refactoring sprint.

Step 4: Consuming It from Your Frontend

A simple hook to call the pipeline from a Next.js page:

// hooks/useSeoGenerator.ts
import { useState } from "react";
import { SeoOutput } from "@/lib/seo/types";

export function useSeoGenerator() {
  const [result, setResult] = useState<SeoOutput | null>(null);
  const [loading, setLoading] = useState(false);

  async function generate(url: string, pageContent: string, targetKeyword?: string) {
    setLoading(true);
    try {
      const res = await fetch("/api/seo", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ url, pageContent, targetKeyword }),
      });
      const data = await res.json();
      setResult(data);
    } finally {
      setLoading(false);
    }
  }

  return { result, loading, generate };
}

Call it from any component:

const { result, loading, generate } = useSeoGenerator();

// On button click or form submit:
await generate("https://example.com/blog/post", articleText, "Next.js SEO");

// result now contains title, description, keywords, schema — ready to inject

You now have a working AI SEO tool pipeline that runs entirely on your infrastructure, with the provider as a runtime config value.

Bonus: Where a Dedicated SEO Package Saves Time

The adapter pattern above handles the AI layer, but you still need to handle things like robots.txt generation, sitemap injection, JSON-LD rendering, and keyword clustering logic. Rolling all of that from scratch adds up.

This is where I started using @power-seo as the pipeline's output consumer — it takes the structured JSON your provider generates and handles the Next.js <Head> injection, schema rendering, and sitemap updates automatically. Worth checking out if you want to skip that plumbing. There's also a deeper writeup on using it with this exact adapter pattern over at ccbd.dev.

What I Learned

Couple to the interface, not the SDK. The 30 minutes you spend writing an adapter pays back every time you switch models — and you will switch models.
Keep prompts in a shared module. Provider-specific quirks (like Anthropic's JSON formatting behavior) belong in the adapter, not the prompt. One prompt file means one place to improve output quality.
Use response_format: json_object (OpenAI) or explicit JSON instructions (Anthropic) — don't parse unstructured text from a model if you need structured data. You'll lose hours chasing intermittent parse errors.
Test with the cheapest model first. GPT-4o-mini and Claude Haiku are fast and cheap enough to run on every save in development. Use the heavyweight models only when you're tuning final output quality.

If you want to try this approach, here's the full writeup with repo links: https://ccbd.dev/blog/ai-seo-tool-that-works-with-every-llm-a-developers-guide-in-2026

What's your setup?

Genuinely curious: what is the best AI SEO tool for Next.js developers in 2026? Are you rolling your own pipeline, using a SaaS wrapper, or going full DIY with raw API calls? Drop your stack in the comments — especially if you've found a clever way to handle provider fallback when rate limits hit.

Stop Letting Googlebot Guess Fix Your React App's SEO Right

Alamin Sarker — Thu, 16 Apr 2026 06:34:53 +0000

I spent 3 hours debugging why Google couldn't index my React app. I checked robots.txt, verified the sitemap, and re-read Google Search Console docs twice. The fix turned out to be 4 lines of code I was missing in every single route. If you've ever shipped a React SPA and wondered why your pages weren't showing up in search results — this one's for you. By the end of this article, you'll know exactly why Googlebot struggles with SPAs, how to fix it with SSR or pre-rendering, and how to manage meta tags dynamically without losing your mind.

Why Googlebot Struggles With React SPAs

Here's the uncomfortable truth: Googlebot can execute JavaScript — but it doesn't do it the same way your browser does.

When Googlebot crawls a plain HTML page, it reads content immediately. When it hits a React SPA, it has to:

Download the JS bundle
Execute React
Wait for data fetches to resolve
Then read the DOM

That "wait" is the problem. Google runs JS crawling in a secondary wave that can be delayed by days. Worse, if your app does anything async before rendering visible text — an API call, a loading spinner, a suspense boundary — Googlebot might index the blank shell instead of your actual content.

Here's a simple test. In your browser, do View Page Source (not DevTools — actual source). If you see a nearly empty <div id="root"></div>, that's what Googlebot sees too, at least initially.

# Quick sanity check — fetch your page like Googlebot does
curl -A "Mozilla/5.0 (compatible; Googlebot/2.1)" https://yoursite.com/your-page

If that curl returns minimal HTML, you have a problem worth solving.

Fix 1: Add Dynamic Meta Tags Per Route

Even if Googlebot eventually renders your page, without proper <title> and <meta> tags per route, your SEO is just guesswork. A single static title in index.html means every page on your site looks identical to a search crawler.

The most common fix is react-helmet-async:

npm install react-helmet-async

Wrap your app:

// main.jsx or App.jsx
import { HelmetProvider } from 'react-helmet-async';

function App() {
  return (
    <HelmetProvider>
      <Router>
        <Routes />
      </Router>
    </HelmetProvider>
  );
}

Then in each page component, declare exactly what that page should tell search engines:

// pages/BlogPost.jsx
import { Helmet } from 'react-helmet-async';

function BlogPost({ post }) {
  return (
    <>
      <Helmet>
        <title>{post.title} | My Blog</title>
        <meta name="description" content={post.excerpt} />
        <meta property="og:title" content={post.title} />
        <meta property="og:description" content={post.excerpt} />
        <meta property="og:image" content={post.coverImage} />
        <link rel="canonical" href={`https://myblog.com/posts/${post.slug}`} />
      </Helmet>

      <article>
        <h1>{post.title}</h1>
        <p>{post.content}</p>
      </article>
    </>
  );
}

Result: Every route now has unique, crawlable metadata. No more Google showing "React App" as the title for your carefully-written product pages.

Fix 2: Pre-render Static Routes (Without Full SSR)

Full server-side rendering with Next.js is the gold standard, but it's not always an option — especially if you're maintaining an existing Vite or CRA app you don't want to rewrite.

Pre-rendering is the middle ground. You generate static HTML snapshots of your routes at build time, so crawlers always get real content without waiting for JS.

vite-plugin-ssg (for Vite) or react-snap work well for this. Here's a practical setup with vite-plugin-ssg:

npm install vite-plugin-ssg

// vite.config.js
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import { VitePluginSSG } from 'vite-plugin-ssg';

export default defineConfig({
  plugins: [react(), VitePluginSSG()],
});

// src/main.jsx — change the export pattern
import { ViteSSG } from 'vite-plugin-ssg';
import App from './App';
import routes from './routes';

export const createApp = ViteSSG(App, { routes });

Run vite build and you'll get pre-rendered HTML for every route defined in your router. Googlebot hits real HTML — no JS execution needed.

Result: Your /about, /pricing, and /blog/[slug] pages all arrive as fully-formed HTML. Crawl budget is used efficiently, and indexing happens in the first wave, not the secondary JS queue.

Fix 3: Automate Structured Data (JSON-LD)

This one is often skipped entirely, but structured data is how you communicate meaning to search engines — not just content. It's how you get rich snippets, FAQ dropdowns, and review stars in SERPs.

Adding it manually to every page is tedious and error-prone. A cleaner pattern is a reusable component:

// components/StructuredData.jsx
function StructuredData({ type, data }) {
  const schema = {
    '@context': 'https://schema.org',
    '@type': type,
    ...data,
  };

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

// Usage in a product page
function ProductPage({ product }) {
  return (
    <>
      <Helmet>
        <title>{product.name}</title>
      </Helmet>

      <StructuredData
        type="Product"
        data={{
          name: product.name,
          description: product.description,
          image: product.imageUrl,
          offers: {
            '@type': 'Offer',
            price: product.price,
            priceCurrency: 'USD',
          },
        }}
      />

      <main>{/* your page content */}</main>
    </>
  );
}

No library needed — just a wrapper around a <script> tag that keeps your schema co-located with your components rather than buried in config files.

Fix 4: Use a Meta Tag Management Package When It Gets Complex

Once you're managing dozens of routes, dynamic OG images, canonical URLs, and multiple schema types, maintaining all of it by hand becomes a real liability. This is where dedicated tooling helps.

One package worth knowing about is @power-seo, which consolidates meta tag management, structured data injection, and sitemap generation into a single API. I came across it while building a content-heavy app for ccbd.dev and found it useful for keeping SEO logic out of individual page components.

npm install @power-seo

import { SEOHead } from '@power-seo';

function ArticlePage({ article }) {
  return (
    <>
      <SEOHead
        title={article.title}
        description={article.summary}
        canonical={`https://ccbd.dev/articles/${article.slug}`}
        openGraph={{
          type: 'article',
          image: article.ogImage,
          publishedTime: article.publishedAt,
        }}
        schema={{
          type: 'Article',
          headline: article.title,
          author: article.author,
        }}
      />
      <article>{/* content */}</article>
    </>
  );
}

It's not magic — under the hood it's doing the same things I showed you above. But for larger projects, the unified API reduces the chance of someone adding a page and forgetting the canonical tag or the OG image. Use it if you're maintaining a team codebase where consistency matters more than control.

What I Learned (The Hard Way)

View Page Source is your most honest SEO audit tool. DevTools lies to you — it shows you the rendered DOM. Page Source shows you what crawlers actually receive first.
Pre-rendering beats SSR for most content sites. Unless you need real-time personalization, static HTML snapshots are faster to serve, simpler to deploy, and crawlers love them.
One missing canonical tag can cause duplicate content penalties. If your React router allows /about and /about/ to both resolve, add a canonical on every page. No exceptions.
Structured data is the SEO multiplier nobody talks about enough. Getting your pages indexed is step one; getting rich snippets is step two and it's almost free if you add JSON-LD from day one.

If you want to explore the meta management approach further, the @power-seo npm package is at: https://www.npmjs.com/package/@power-seo/react

How Does Your Team Handle This?

I'm genuinely curious — are you using Next.js for SSR from the start, or retrofitting SEO onto an existing SPA? Have you found pre-rendering good enough, or did you eventually migrate to a framework with built-in SSR?

Drop a comment below. These are the kinds of tradeoffs that rarely have a clean universal answer, and the real-world context from other projects is always more useful than any tutorial (including this one).