@soloworks/smking-next

AI-native SEO (AEO) for Next.js. One server component injects JSON-LD, OG tags, AI summary, and FAQ on every page so AI crawlers (ChatGPT, Perplexity, Google AI) can cite your content.

• One server component in your root layout — every URL gets its own AEO content automatically (/products/nike-air, /products/adidas/red, anything dynamic, no codemod needed).
• Fail-fast, fail-open. 2-second timeout + Next.js ISR — if smking is down, your page renders without injection. Never blocks.
• Push updates — webhook handler invalidates only the changed paths via revalidateTag.

Install

Don't follow this README to install. Your smking dashboard generates a per-site install prompt with the real SMKING_API_KEY, SMKING_BASE_URL, and (if you use CMS) SMKING_WEBHOOK_SECRET baked in, plus copy-pasteable layout / route shims. The prompt is the source of truth and stays in sync with the SDK version.

Two ways to get it:

# Option 1 — one-shot wizard (installs deps + writes env + runs doctor)
npx @soloworks/smking-wizard

# Option 2 — copy the prompt manually from your smking dashboard's
# install panel into your editor / coding agent.

The wizard owns: pnpm add @soloworks/smking-next, <SmkingAEO /> mount in app/layout.tsx, env writes, app/api/smking/webhook/route.ts shim, and doctor verification.

How metadata wins / loses

Both <SmkingAEO /> and your own generateMetadata emit head tags. Next.js + React 19 head dedup applies last-write-wins:

• No generateMetadata → smking's <title> / og:* are used.
• You write generateMetadata in a layout / page → your tags override smking's for that route segment.

This is the pattern: smking provides AEO/SEO baseline, you override per-page when you want. No HOF, no codemod.

For client pages ('use client') that need dynamic metadata, write a sibling layout.tsx with generateMetadata — standard Next.js workflow, unrelated to smking.

How outage tolerance works

getAeoContent wraps fetch with AbortSignal.timeout(2000) and Next.js ISR (next: { revalidate: 3600, tags: ['smking:path:<path>'] }):

• Cache hit (the common path): zero network. Tags allow webhook-driven invalidation.
• Cache miss + smking healthy: one network roundtrip, response cached for 1h.
• Cache miss + smking down / hung: returns null after at most 2s, page renders without injection. Next.js ISR retries on the next request after revalidate.
• 5xx / 4xx / parse error: same fail-open path.

No circuit breaker, no retry, no status command — Next.js infrastructure already covers what those would do.

API

<SmkingAEO /> props

interface SmkingAEOProps {
  apiKey: string;        // required
  baseUrl?: string;      // override SMKING_BASE_URL env
  path?: string;         // explicit path; auto-resolved from headers() otherwise
  revalidate?: number;   // ISR seconds; default 3600 (1h)
}

Path auto-detection works for any URL schema (/products/[slug], /shop/[cat]/[id]/[variant]). Pass path explicitly only for static-export contexts where headers() is unavailable.

getAeoContent(params)

Lower-level helper if you want to fetch the AEO response and render yourself. Same params, returns Promise<AeoResponse | null>.

import { getAeoContent } from '@soloworks/smking-next';

const aeo = await getAeoContent({ apiKey: ..., path: '/products/abc' });
if (aeo?.status === 'ready') {
  // aeo.jsonLd, aeo.faq, aeo.summary, aeo.seo, aeo.chatLinks, ...
}

Webhook payload

POST /api/smking-revalidate
Authorization: Bearer <SMKING_WEBHOOK_TOKEN>
Content-Type: application/json

{ "paths": ["/products/abc", "/products/xyz"] }

Response: { revalidated: number, errors: number }. errors > 0 means some tags couldn't be revalidated (others still succeeded — partial-success delivery).

Versions

See CHANGELOG.md. Aligned with smking/laravel for SaaS-side parity.

License

MIT