nextjs-seo

SEO breaks silently. nextjs-seo is a Claude Code plugin that finds those breaks in your Next.js source, tells you how to fix each one, and checks the fix against what the running site actually serves.

txt

/plugin marketplace add AbdelrahmanMostafa0/nextjs-seo-skill
/plugin install nextjs-seo@nextjs-seo

GitHub ↗ · The CLI version: next-seo-doctor · How I wired this site's own SEO

What it does

next-seo-doctor checks what shipped. This plugin checks what you're about to ship. It reads your App Router code, flags each problem with a file:line and a fix, and can apply the fix for you. It also knows the current Metadata API and Google's rules, so you don't get advice from 2021.

Restart Claude Code after installing. Update later with /plugin marketplace update nextjs-seo.

Commands

Command	What it does
`/nextjs-seo:check [dir]`	Static scan of the codebase. Every finding comes with `file:line` and a fix. Start here.
`/nextjs-seo:fix [rule-id]`	Applies the fixes one rule at a time, then re-scans to prove it. Asks before changing what's indexed.
`/nextjs-seo:tools [dir]`	Finds Search Console, Bing Webmaster, GTM, GA4, Vercel Analytics, Plausible, PostHog, Clarity, Meta Pixel and more, and shows how to connect what's missing.
`/nextjs-seo:live <url>`	Fetches a running page like a crawler: status, canonical, OG tags, JSON-LD, robots.txt, the sitemap, and soft 404s.
`/nextjs-seo:page <route>`	Reviews one route's effective metadata, after Next.js's shallow merge.
`/nextjs-seo:setup [site-type]`	Builds baseline SEO: site config, `metadataBase`, a metadata helper, sitemap, robots, JSON-LD, OG image.
`/nextjs-seo:schema [site-type]`	Adds an `@id`-linked, XSS-safe JSON-LD graph (blog, ecommerce, saas, local, realestate, portfolio, docs).
`/nextjs-seo:ai [policy]`	Sets AI crawler rules (GPTBot, ClaudeBot, PerplexityBot, Google-Extended…) in robots, plus an optional `llms.txt`.
`/nextjs-seo:rules`	Lists every check the scanner runs.

You don't have to type a command. The nextjs-seo skill loads on its own when you ask Claude things like "add a sitemap", "why is og:url wrong on my blog posts", or "audit my SEO".

Why it's cheap on tokens

check, tools, and fix don't have Claude explore your repo. A zero-dependency Node script reads the source as text, runs 36 rules, and prints a few lines per finding. Claude reads that output and opens only the flagged lines. A full /nextjs-seo:check on the test fixture (22 findings, each explained with a code fix) cost under one cent on Haiku.

The same script runs without Claude, for example in CI:

bash

node scripts/seo-check.mjs path/to/next-app            # human-readable, exit 1 on errors
node scripts/seo-check.mjs path/to/next-app --json     # machine-readable
node scripts/seo-check.mjs . --only sitemap-fake-lastmod,jsonld-unescaped

What it checks

Crawl and index blockers, metadata, sitemap and robots, structured data, previews, i18n, and performance. A sample:

noindex in a layout with no environment check
robots blocking / or /_next/
params read synchronously (it's a Promise since Next 15)
canonical or hreflang set in a layout, so every child page inherits it (the canonical trap)
openGraph.url in a layout, or twitter.images overriding per-page OG images
new Date() as sitemap lastModified (why that lies)
robots Disallow lines that leak sensitive paths
JSON-LD serialized without escaping <, an XSS sink
FAQPage and HowTo schema, whose rich results Google retired
localized routes without hreflang, or without x-default (more on that)
deprecated metadata.themeColor and the deprecated next/image priority prop (Next 16)
analytics loaded beforeInteractive, GTM plus direct GA4 double counting, no consent handling

It stays out of your env files

The plugin ships a PreToolUse hook that blocks any tool call that reads, writes, lists, greps, sources, or loads .env, .env.*, .envrc, or .dev.vars. That includes dotenv, --env-file, source .env, and printenv. .env.example and other templates stay accessible.

The hook stays on in every session while the plugin is enabled, not only during SEO commands. Secrets stay out of the model's context whatever you're doing. For the same reason, the commands never run next dev, next build, or next start: Next.js loads env files automatically. Start the app yourself and point /nextjs-seo:live at it.

FAQ

How is it different from next-seo-doctor?

next-seo-doctor crawls a running site and checks the HTML it actually serves. nextjs-seo reads your source code inside Claude Code, so it catches problems before you build, points at the exact file and line, and can apply the fix. Use both: the plugin while you write, the CLI against staging.

Does it read my env files?

No. The scanner never opens env files, and the plugin ships a PreToolUse hook that blocks any tool call that would read, list, grep, source, or load one. Templates like .env.example stay accessible.

Does it run my app?

No. The scanner reads source files as text and never executes them. The commands never run next dev, next build, or next start, because Next.js loads env files on its own. Start the app yourself and point /nextjs-seo:live at it.

Can I use the scanner without Claude?

Yes. scripts/seo-check.mjs is a zero-dependency Node script. Run it directly or in CI: it exits 1 when it finds errors, and --json gives machine-readable output.

Does it work with the Pages Router?

It's built for the App Router: the Metadata API, sitemap.ts, robots.ts, and opengraph-image routes. A Pages Router project isn't the target, so expect gaps.

Is it free?

Yes, MIT licensed.

New rules and commands are welcome: see CONTRIBUTING.md. A star on GitHub helps other people find it.