Open-source SEO, GEO, and marketing skills for AI agents.
feat(nextjs-blog): add image-first post hero
Yuting Zhongc061814fa25c
diff --git a/.github/workflows/npm-publish-nextjs-blog.yml b/.github/workflows/npm-publish-nextjs-blog.ymlindex 4f11f5b1..ab2e516d 100644--- a/.github/workflows/npm-publish-nextjs-blog.yml+++ b/.github/workflows/npm-publish-nextjs-blog.yml@@ -48,9 +48,9 @@ jobs:if: steps.version.outputs.skip != 'true'run: npm install- - name: Build+ - name: Test and buildif: steps.version.outputs.skip != 'true'- run: npm run build+ run: npm test- name: Publish ${{ steps.version.outputs.local }}if: steps.version.outputs.skip != 'true'diff --git a/notfair-nextjs-blog/README.md b/notfair-nextjs-blog/README.mdindex 19123a32..53ccda19 100644--- a/notfair-nextjs-blog/README.md+++ b/notfair-nextjs-blog/README.md@@ -22,7 +22,24 @@ npm install --save-dev @types/sanitize-htmlNOTFAIR_SEO_API_KEY=nfbl_...```-4. Publish NotFair posts under `/blog/{slug}`. The dashboard derives the+4. Allow NotFair-hosted article images through Next.js image optimization.+ Preserve your existing `next.config.js` or `next.config.ts` and append the+ following entry to `images.remotePatterns`:++```js+images: {+ remotePatterns: [+ // ...your existing image patterns,+ {+ protocol: "https",+ hostname: "notfair.co",+ pathname: "/api/seo/**",+ },+ ],+},+```++5. Publish NotFair posts under `/blog/{slug}`. The dashboard derives theverification URL automatically. If `/blog` already exists, merge NotFairinto it as an additional source rather than replacing the route.@@ -135,6 +152,7 @@ of the host application's design system.`app/blog/page.tsx`:```tsx+import Image from "next/image";import Link from "next/link";import { getSeoPosts } from "notfair-nextjs-blog";@@ -145,6 +163,7 @@ export default async function BlogIndex() {<h1>Blog</h1>{posts.map((p) => (<article key={p.slug}>+ <Image src={p.image_url} alt={p.title} width={1600} height={900} /><Link href={`/blog/${p.slug}`}>{p.title}</Link></article>))}@@ -158,6 +177,7 @@ export default async function BlogIndex() {```tsximport { notFound } from "next/navigation";import { getSeoPost } from "notfair-nextjs-blog";+import { NotFairPostHero } from "notfair-nextjs-blog/react";import { sanitizeNotFairArticleHtml } from "@/lib/notfair-article";import styles from "../notfair-article.module.css";@@ -171,7 +191,7 @@ export default async function BlogPost({if (!post) notFound();return (<article>- <h1>{post.title}</h1>+ <NotFairPostHero post={post} /><divclassName={styles.articleContent}dangerouslySetInnerHTML={{@@ -183,6 +203,13 @@ export default async function BlogPost({}```+`NotFairPostHero` is an optional, image-first Server Component exported from+`notfair-nextjs-blog/react`. It renders the generated 16:9 cover before the+article `<h1>` and accepts `className`, `imageClassName`, and `titleClassName`+for the host design system. Existing data-client imports and page templates are+unchanged when upgrading; adopt the component when you want the canonical+header.+Responses revalidate hourly by default (`{ revalidate }` option to change).## Existing `/blog`@@ -212,6 +239,7 @@ NotFair only as a fallback:```tsximport { notFound } from "next/navigation";import { getBlogPostWithSeoFallback } from "notfair-nextjs-blog";+import { NotFairPostHero } from "notfair-nextjs-blog/react";const result = await getBlogPostWithSeoFallback(slug, getExistingPost);if (!result) notFound();@@ -222,7 +250,7 @@ if (result.source === "existing") {return (<article>- <h1>{result.post.title}</h1>+ <NotFairPostHero post={result.post} /><divclassName={styles.articleContent}dangerouslySetInnerHTML={{@@ -246,8 +274,10 @@ reachable at the configured `/blog/{slug}` URL for link verification.## API-- `getSeoPosts({ revalidate? })` → `[{ id, title, slug, published_at, created_at }]`+- `getSeoPosts({ revalidate? })` → summaries including `image_url`, tags, and timestamps- `getSeoPost(slug, { revalidate? })` → adds `content_html`, or `null`- `mergeBlogPosts(existing, seo)` → discriminated list; existing slugs win- `getBlogPostWithSeoFallback(slug, getExistingPost, { revalidate? })` →`{ source, post }`, or `null`+- `NotFairPostHero` from `notfair-nextjs-blog/react` → optional image-first+ article cover and title; existing renderers remain compatiblediff --git a/notfair-nextjs-blog/package.json b/notfair-nextjs-blog/package.jsonindex 1f5f5d57..b003a4b0 100644--- a/notfair-nextjs-blog/package.json+++ b/notfair-nextjs-blog/package.json@@ -1,6 +1,6 @@{"name": "notfair-nextjs-blog",- "version": "0.3.1",+ "version": "0.4.0","description": "Render your NotFair SEO exchange posts on a Next.js blog — server-side content pulls with your private site API key.","license": "MIT","type": "module",@@ -10,6 +10,10 @@".": {"types": "./dist/index.d.ts","import": "./dist/index.js"+ },+ "./react": {+ "types": "./dist/react.d.ts",+ "import": "./dist/react.js"}},"sideEffects": false,@@ -19,7 +23,7 @@],"scripts": {"build": "tsc -p tsconfig.json",- "test": "npm run build && node --test test/*.test.mjs",+ "test": "npm run build && node --test test/*.test.mjs && next build test/next-app --webpack","prepublishOnly": "tsc -p tsconfig.json"},"keywords": [@@ -37,10 +41,12 @@"directory": "notfair-nextjs-blog"},"peerDependencies": {- "next": ">=14"+ "next": ">=14",+ "react": ">=18"},"devDependencies": {"typescript": "^5.6.0",- "@types/node": "^22.0.0"+ "@types/node": "^22.0.0",+ "@types/react": "^19.0.0"}}diff --git a/notfair-nextjs-blog/src/index.ts b/notfair-nextjs-blog/src/index.tsindex b6f08bd6..f432c79b 100644--- a/notfair-nextjs-blog/src/index.ts+++ b/notfair-nextjs-blog/src/index.ts@@ -15,7 +15,7 @@ export type SeoPostSummary = {slug: string;meta_description: string | null;tags: string[];- /** Generated title-card image (1200×630) — thumbnail / og:image. */+ /** Generated 16:9 title-card image — article hero, thumbnail, and og:image. */image_url: string;reading_time_minutes: number | null;published_at: string | null;diff --git a/notfair-nextjs-blog/src/react.tsx b/notfair-nextjs-blog/src/react.tsxnew file mode 100644index 00000000..d84abe28--- /dev/null+++ b/notfair-nextjs-blog/src/react.tsx@@ -0,0 +1,50 @@+import Image from "next/image.js";+import type { CSSProperties } from "react";+import type { SeoPostSummary } from "./index.js";++export type NotFairPostHeroProps = {+ /** A full post or summary returned by notfair-nextjs-blog. */+ post: Pick<SeoPostSummary, "image_url" | "title">;+ className?: string;+ imageClassName?: string;+ titleClassName?: string;+ /** Above-the-fold article heroes should keep the default eager priority. */+ priority?: boolean;+ /** Responsive image hint passed to next/image. */+ sizes?: string;+ imageStyle?: CSSProperties;+};++/**+ * Canonical NotFair article header. It deliberately owns only the cover and+ * title so host apps retain control of their typography and sanitized article+ * body. The cover is always the first visible element.+ *+ * Import from `notfair-nextjs-blog/react`; the root data-client export remains+ * UI-free and fully backward compatible.+ */+export function NotFairPostHero({+ post,+ className,+ imageClassName,+ titleClassName,+ priority = true,+ sizes = "(max-width: 768px) 100vw, 1200px",+ imageStyle,+}: NotFairPostHeroProps) {+ return (+ <header className={className}>+ <Image+ src={post.image_url}+ alt={post.title}+ width={1600}+ height={900}+ sizes={sizes}+ priority={priority}+ className={imageClassName}+ style={{ width: "100%", height: "auto", ...imageStyle }}+ />+ <h1 className={titleClassName}>{post.title}</h1>+ </header>+ );+}diff --git a/notfair-nextjs-blog/test/compatibility.test.mjs b/notfair-nextjs-blog/test/compatibility.test.mjsnew file mode 100644index 00000000..14f0603e--- /dev/null+++ b/notfair-nextjs-blog/test/compatibility.test.mjs@@ -0,0 +1,19 @@+import assert from "node:assert/strict";+import { readFile } from "node:fs/promises";+import { fileURLToPath } from "node:url";+import test from "node:test";++const packageJson = JSON.parse(+ await readFile(fileURLToPath(new URL("../package.json", import.meta.url)), "utf8"),+);+const rootClient = await readFile(+ fileURLToPath(new URL("../dist/index.js", import.meta.url)),+ "utf8",+);++test("the existing root data client remains UI-free", () => {+ assert.deepEqual(Object.keys(packageJson.exports), [".", "./react"]);+ assert.equal(packageJson.exports["."].import, "./dist/index.js");+ assert.equal(packageJson.exports["./react"].import, "./dist/react.js");+ assert.doesNotMatch(rootClient, /next\/image|react\/jsx-runtime|NotFairPostHero/);+});diff --git a/notfair-nextjs-blog/test/next-app/.gitignore b/notfair-nextjs-blog/test/next-app/.gitignorenew file mode 100644index 00000000..6f92be1a--- /dev/null+++ b/notfair-nextjs-blog/test/next-app/.gitignore@@ -0,0 +1,3 @@+.next/+next-env.d.ts+tsconfig.jsondiff --git a/notfair-nextjs-blog/test/next-app/app/layout.tsx b/notfair-nextjs-blog/test/next-app/app/layout.tsxnew file mode 100644index 00000000..e53180ee--- /dev/null+++ b/notfair-nextjs-blog/test/next-app/app/layout.tsx@@ -0,0 +1,9 @@+import type { ReactNode } from "react";++export default function RootLayout({ children }: { children: ReactNode }) {+ return (+ <html lang="en">+ <body>{children}</body>+ </html>+ );+}diff --git a/notfair-nextjs-blog/test/next-app/app/page.tsx b/notfair-nextjs-blog/test/next-app/app/page.tsxnew file mode 100644index 00000000..c40b03d7--- /dev/null+++ b/notfair-nextjs-blog/test/next-app/app/page.tsx@@ -0,0 +1,14 @@+import { NotFairPostHero } from "notfair-nextjs-blog/react";++export default function Page() {+ return (+ <main>+ <NotFairPostHero+ post={{+ title: "A practical resource guide",+ image_url: "https://notfair.co/api/seo/og?postId=32",+ }}+ />+ </main>+ );+}diff --git a/notfair-nextjs-blog/test/next-app/next.config.mjs b/notfair-nextjs-blog/test/next-app/next.config.mjsnew file mode 100644index 00000000..79e1c57f--- /dev/null+++ b/notfair-nextjs-blog/test/next-app/next.config.mjs@@ -0,0 +1,14 @@+/** @type {import("next").NextConfig} */+const nextConfig = {+ images: {+ remotePatterns: [+ {+ protocol: "https",+ hostname: "notfair.co",+ pathname: "/api/seo/**",+ },+ ],+ },+};++export default nextConfig;diff --git a/notfair-nextjs-blog/test/react.test.mjs b/notfair-nextjs-blog/test/react.test.mjsnew file mode 100644index 00000000..05ce3773--- /dev/null+++ b/notfair-nextjs-blog/test/react.test.mjs@@ -0,0 +1,37 @@+import assert from "node:assert/strict";+import test from "node:test";++import { NotFairPostHero } from "../dist/react.js";++const post = {+ title: "A practical resource guide",+ image_url: "https://notfair.co/api/seo/og?postId=32",+};++test("NotFairPostHero always renders the cover before the article title", () => {+ const hero = NotFairPostHero({ post });+ const [cover, title] = hero.props.children;++ assert.equal(title.type, "h1");+ assert.equal(cover.props.src, post.image_url);+ assert.equal(cover.props.alt, post.title);+ assert.equal(cover.props.width, 1600);+ assert.equal(cover.props.height, 900);+ assert.equal(title.props.children, post.title);+});++test("NotFairPostHero keeps host styling hooks optional", () => {+ const hero = NotFairPostHero({+ post,+ className: "article-header",+ imageClassName: "article-cover",+ titleClassName: "article-title",+ priority: false,+ });+ const [cover, title] = hero.props.children;++ assert.equal(hero.props.className, "article-header");+ assert.equal(cover.props.className, "article-cover");+ assert.equal(title.props.className, "article-title");+ assert.equal(cover.props.priority, false);+});diff --git a/notfair-nextjs-blog/test/readme.test.mjs b/notfair-nextjs-blog/test/readme.test.mjsindex 89195035..2fb4216e 100644--- a/notfair-nextjs-blog/test/readme.test.mjs+++ b/notfair-nextjs-blog/test/readme.test.mjs@@ -18,3 +18,9 @@ test("README requires sanitized, scoped NotFair article rendering", () => {assert.match(readme, /from "\.\.\/notfair-article\.module\.css"/);assert.doesNotMatch(readme, /dangerouslySetInnerHTML=\{\{ __html: post\.content_html \}\}/);});++test("README uses the canonical image-first article hero", () => {+ assert.match(readme, /NotFairPostHero/);+ assert.match(readme, /notfair-nextjs-blog\/react/);+ assert.doesNotMatch(readme, /<h1>\{post\.title\}<\/h1>\s*<Image src=\{post\.image_url\}/);+});diff --git a/notfair-nextjs-blog/tsconfig.json b/notfair-nextjs-blog/tsconfig.jsonindex 4a7d7f43..8f1190b2 100644--- a/notfair-nextjs-blog/tsconfig.json+++ b/notfair-nextjs-blog/tsconfig.json@@ -3,6 +3,7 @@"target": "ES2022","module": "ESNext","moduleResolution": "bundler",+ "jsx": "react-jsx","lib": ["ES2022", "DOM"],"strict": true,"declaration": true,