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.ymlnew file mode 100644index 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/.gitignorenew file mode 100644index 00000000..e7289959--- /dev/null+++ b/notfair-nextjs-blog/.gitignore@@ -0,0 +1,3 @@+dist/+node_modules/+*.tgzdiff --git a/notfair-nextjs-blog/README.md b/notfair-nextjs-blog/README.mdnew file mode 100644index 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.jsonnew file mode 100644index 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.tsnew file mode 100644index 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.jsonnew file mode 100644index 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"]+}