Skip to content

Open-source SEO, GEO, and marketing skills for AI agents.

feat: notfair-nextjs-blog npm package + publish workflow

Yuting Zhong7c6f227762cd
diff --git a/.github/workflows/npm-publish-nextjs-blog.yml b/.github/workflows/npm-publish-nextjs-blog.yml
new file mode 100644
index 00000000..599c4e2c
--- /dev/null
+++ b/.github/workflows/npm-publish-nextjs-blog.yml
@@ -0,0 +1,59 @@
+name: Publish notfair-nextjs-blog to npm
+
+# Publishes the Next.js blog client when notfair-nextjs-blog/package.json
+# lands on main with a version that isn't on the registry yet. Bump the
+# version in a normal commit and push — no tags or releases to manage.
+# Re-runs on an already-published version are a clean no-op.
+on:
+ push:
+ branches: [main]
+ paths:
+ - "notfair-nextjs-blog/**"
+ workflow_dispatch:
+
+concurrency:
+ group: npm-publish-nextjs-blog
+ cancel-in-progress: false
+
+jobs:
+ publish:
+ # Pure TypeScript, no native deps — ubuntu is fine here (unlike the main
+ # notfair package, which needs macOS ARM64 for its prebuilds).
+ runs-on: ubuntu-latest
+ defaults:
+ run:
+ working-directory: notfair-nextjs-blog
+ steps:
+ - uses: actions/checkout@v4
+
+ # registry-url makes setup-node write an ~/.npmrc that reads
+ # NODE_AUTH_TOKEN.
+ - uses: actions/setup-node@v4
+ with:
+ node-version: 24
+ registry-url: https://registry.npmjs.org
+
+ - name: Skip if this version is already on npm
+ id: version
+ run: |
+ LOCAL=$(node -p "require('./package.json').version")
+ PUBLISHED=$(npm view notfair-nextjs-blog version 2>/dev/null || echo "none")
+ echo "local=$LOCAL published=$PUBLISHED"
+ echo "local=$LOCAL" >> "$GITHUB_OUTPUT"
+ if [ "$LOCAL" = "$PUBLISHED" ]; then
+ echo "skip=true" >> "$GITHUB_OUTPUT"
+ fi
+
+ - name: Install
+ if: steps.version.outputs.skip != 'true'
+ run: npm install
+
+ - name: Build
+ if: steps.version.outputs.skip != 'true'
+ run: npm run build
+
+ - name: Publish ${{ steps.version.outputs.local }}
+ if: steps.version.outputs.skip != 'true'
+ run: npm publish
+ env:
+ NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
diff --git a/notfair-nextjs-blog/.gitignore b/notfair-nextjs-blog/.gitignore
new file mode 100644
index 00000000..e7289959
--- /dev/null
+++ b/notfair-nextjs-blog/.gitignore
@@ -0,0 +1,3 @@
+dist/
+node_modules/
+*.tgz
diff --git a/notfair-nextjs-blog/README.md b/notfair-nextjs-blog/README.md
new file mode 100644
index 00000000..6d1dc7a0
--- /dev/null
+++ b/notfair-nextjs-blog/README.md
@@ -0,0 +1,79 @@
+# notfair-nextjs-blog
+
+Render your [NotFair Backlinks](https://notfair.co/backlinks) exchange posts on
+a Next.js (App Router) blog. Pull model: your site fetches published posts
+server-side from the NotFair content API with a private key — nothing is ever
+pushed to your infrastructure.
+
+## Setup
+
+1. Install the package:
+
+```bash
+npm install notfair-nextjs-blog
+```
+
+2. In the NotFair Backlinks dashboard, create a **Next.js / headless**
+ integration and copy the site API key (shown once).
+3. Add it to your environment — server-side only, never `NEXT_PUBLIC_`:
+
+```bash
+NOTFAIR_BACKLINKS_API_KEY=nfbl_...
+```
+
+4. Set your integration's **public post URL pattern** to where these pages
+ render (e.g. `https://yoursite.com/blog/{slug}`) — link verification crawls
+ it, and hosted links only earn credits once verified.
+
+## Minimal app/blog
+
+`app/blog/page.tsx`:
+
+```tsx
+import Link from "next/link";
+import { getBacklinksPosts } from "notfair-nextjs-blog";
+
+export default async function BlogIndex() {
+ const posts = await getBacklinksPosts();
+ return (
+ <main>
+ <h1>Blog</h1>
+ {posts.map((p) => (
+ <article key={p.slug}>
+ <Link href={`/blog/${p.slug}`}>{p.title}</Link>
+ </article>
+ ))}
+ </main>
+ );
+}
+```
+
+`app/blog/[slug]/page.tsx`:
+
+```tsx
+import { notFound } from "next/navigation";
+import { getBacklinksPost } from "notfair-nextjs-blog";
+
+export default async function BlogPost({
+ params,
+}: {
+ params: Promise<{ slug: string }>;
+}) {
+ const { slug } = await params;
+ const post = await getBacklinksPost(slug);
+ if (!post) notFound();
+ return (
+ <article>
+ <h1>{post.title}</h1>
+ <div dangerouslySetInnerHTML={{ __html: post.content_html }} />
+ </article>
+ );
+}
+```
+
+Responses revalidate hourly by default (`{ revalidate }` option to change).
+
+## API
+
+- `getBacklinksPosts({ revalidate? })` → `[{ id, title, slug, published_at, created_at }]`
+- `getBacklinksPost(slug, { revalidate? })` → adds `content_html`, or `null`
diff --git a/notfair-nextjs-blog/package.json b/notfair-nextjs-blog/package.json
new file mode 100644
index 00000000..138231b8
--- /dev/null
+++ b/notfair-nextjs-blog/package.json
@@ -0,0 +1,44 @@
+{
+ "name": "notfair-nextjs-blog",
+ "version": "0.1.0",
+ "description": "Render your NotFair Backlinks exchange posts on a Next.js blog — server-side content pulls with your private site API key.",
+ "license": "MIT",
+ "type": "module",
+ "main": "dist/index.js",
+ "types": "dist/index.d.ts",
+ "exports": {
+ ".": {
+ "types": "./dist/index.d.ts",
+ "import": "./dist/index.js"
+ }
+ },
+ "sideEffects": false,
+ "files": [
+ "dist",
+ "README.md"
+ ],
+ "scripts": {
+ "build": "tsc -p tsconfig.json",
+ "prepublishOnly": "tsc -p tsconfig.json"
+ },
+ "keywords": [
+ "notfair",
+ "backlinks",
+ "nextjs",
+ "next",
+ "blog",
+ "seo"
+ ],
+ "homepage": "https://notfair.co/backlinks",
+ "repository": {
+ "type": "git",
+ "url": "git+https://github.com/nowork-studio/NotFair.git",
+ "directory": "notfair-nextjs-blog"
+ },
+ "peerDependencies": {
+ "next": ">=14"
+ },
+ "devDependencies": {
+ "typescript": "^5.6.0"
+ }
+}
diff --git a/notfair-nextjs-blog/src/index.ts b/notfair-nextjs-blog/src/index.ts
new file mode 100644
index 00000000..fc9f80b8
--- /dev/null
+++ b/notfair-nextjs-blog/src/index.ts
@@ -0,0 +1,65 @@
+/**
+ * notfair-nextjs-blog — server-side client for the NotFair Backlinks
+ * content API (the "Next.js / headless" integration).
+ *
+ * Usage: set NOTFAIR_BACKLINKS_API_KEY in your environment (server-only —
+ * never expose it to the client bundle), then call these from Server
+ * Components or route handlers. See README.md for a copy-paste app/blog.
+ */
+
+const API_BASE = process.env.NOTFAIR_BACKLINKS_API_URL ?? "https://notfair.co/api/backlinks/content";
+
+export type BacklinksPostSummary = {
+ id: number;
+ title: string;
+ slug: string;
+ published_at: string | null;
+ created_at: string;
+};
+
+export type BacklinksPost = BacklinksPostSummary & { content_html: string };
+
+function apiKey(): string {
+ const key = process.env.NOTFAIR_BACKLINKS_API_KEY;
+ if (!key) {
+ throw new Error(
+ "notfair-nextjs-blog: NOTFAIR_BACKLINKS_API_KEY is not set. Create the key in your NotFair Backlinks dashboard (Integrations → Next.js).",
+ );
+ }
+ return key;
+}
+
+/** Next.js extends fetch's RequestInit with `next` — typed locally so the
+ * package builds standalone without Next's global type augmentation. */
+type NextFetchInit = RequestInit & { next?: { revalidate: number } };
+
+async function contentFetch(path: string, revalidate: number): Promise<Response> {
+ const init: NextFetchInit = {
+ headers: { authorization: `Bearer ${apiKey()}` },
+ // Cached server-side; posts publish on a schedule, hourly is plenty.
+ next: { revalidate },
+ };
+ return fetch(`${API_BASE}${path}`, init);
+}
+
+/** List published exchange posts (no bodies — cheap for blog indexes). */
+export async function getBacklinksPosts(
+ opts: { revalidate?: number } = {},
+): Promise<BacklinksPostSummary[]> {
+ const res = await contentFetch("", opts.revalidate ?? 3600);
+ if (!res.ok) return [];
+ const body = (await res.json().catch(() => null)) as { posts?: BacklinksPostSummary[] } | null;
+ return body?.posts ?? [];
+}
+
+/** Fetch one published post with its full HTML body. Returns null if the
+ * slug doesn't exist or isn't published. */
+export async function getBacklinksPost(
+ slug: string,
+ opts: { revalidate?: number } = {},
+): Promise<BacklinksPost | null> {
+ const res = await contentFetch(`?slug=${encodeURIComponent(slug)}`, opts.revalidate ?? 3600);
+ if (!res.ok) return null;
+ const body = (await res.json().catch(() => null)) as { post?: BacklinksPost } | null;
+ return body?.post ?? null;
+}
diff --git a/notfair-nextjs-blog/tsconfig.json b/notfair-nextjs-blog/tsconfig.json
new file mode 100644
index 00000000..4a7d7f43
--- /dev/null
+++ b/notfair-nextjs-blog/tsconfig.json
@@ -0,0 +1,16 @@
+{
+ "compilerOptions": {
+ "target": "ES2022",
+ "module": "ESNext",
+ "moduleResolution": "bundler",
+ "lib": ["ES2022", "DOM"],
+ "strict": true,
+ "declaration": true,
+ "outDir": "dist",
+ "rootDir": "src",
+ "skipLibCheck": true,
+ "esModuleInterop": true,
+ "forceConsistentCasingInFileNames": true
+ },
+ "include": ["src"]
+}