Skip to content

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.yml
index 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 build
if: 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.md
index 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-html
NOTFAIR_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 the
verification URL automatically. If `/blog` already exists, merge NotFair
into 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() {
```tsx
import { 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} />
<div
className={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:
```tsx
import { 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} />
<div
className={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 compatible
diff --git a/notfair-nextjs-blog/package.json b/notfair-nextjs-blog/package.json
index 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.ts
index 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.tsx
new file mode 100644
index 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.mjs
new file mode 100644
index 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/.gitignore
new file mode 100644
index 00000000..6f92be1a
--- /dev/null
+++ b/notfair-nextjs-blog/test/next-app/.gitignore
@@ -0,0 +1,3 @@
+.next/
+next-env.d.ts
+tsconfig.json
diff --git a/notfair-nextjs-blog/test/next-app/app/layout.tsx b/notfair-nextjs-blog/test/next-app/app/layout.tsx
new file mode 100644
index 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.tsx
new file mode 100644
index 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.mjs
new file mode 100644
index 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.mjs
new file mode 100644
index 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.mjs
index 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.json
index 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,