Frameworks
@skyscribe-sdk/next is for the Next.js 13+ App Router. Its createScribePublication factory gives you ready-made generateStaticParams and generateMetadata implementations, and documentMetadata / publicationMetadata build complete Open Graph metadata from fetched data. You fetch the content itself with @skyscribe-sdk/core, which the package installs for you.
npm install @skyscribe-sdk/next
Call createScribePublication once per Publication, outside your components:
// lib/scribe.ts
import { createScribePublication } from '@skyscribe-sdk/next';
export const AUTHOR = 'alice.bsky.social';
export const PUBLICATION_URL = 'https://alice.bsky.social';
export const scribe = createScribePublication(AUTHOR, PUBLICATION_URL);
Route param names
The generated params are named categorySlug and documentSlug, so your folders must be [categorySlug] and [documentSlug]. The examples use Next.js 15, where params is a Promise. On Next.js 13 and 14 it's a plain object; await works on both.
// app/blog/page.tsx
import { fetchPublication } from '@skyscribe-sdk/core';
import { scribe, AUTHOR, PUBLICATION_URL } from '@/lib/scribe';
export const generateMetadata = scribe.generatePublicationMetadata;
export default async function BlogPage() {
const publication = await fetchPublication(AUTHOR, PUBLICATION_URL);
return (
<main>
<h1>{publication.name}</h1>
{publication.categories.map((category) => (
<section key={category.slug}>
<h2>{category.title}</h2>
<ul>
{category.documents.map((ref) => (
<li key={ref.uri}>
<a href={`/blog/${category.slug}/${ref.slug}`}>{ref.title}</a>
</li>
))}
</ul>
</section>
))}
</main>
);
}
// app/blog/[categorySlug]/page.tsx
import { notFound } from 'next/navigation';
import { fetchPublication } from '@skyscribe-sdk/core';
import { scribe, AUTHOR, PUBLICATION_URL } from '@/lib/scribe';
type Props = { params: Promise<{ categorySlug: string }> };
export const generateStaticParams = scribe.generateCategoryParams;
export async function generateMetadata({ params }: Props) {
const { categorySlug } = await params;
return scribe.generateCategoryMetadata(categorySlug);
}
export default async function CategoryPage({ params }: Props) {
const { categorySlug } = await params;
const publication = await fetchPublication(AUTHOR, PUBLICATION_URL);
const category = publication.categories.find((c) => c.slug === categorySlug);
if (!category) notFound();
return (
<section>
<h1>{category.title}</h1>
<ul>
{category.documents.map((ref) => (
<li key={ref.uri}>
<a href={`/blog/${category.slug}/${ref.slug}`}>{ref.title}</a>
</li>
))}
</ul>
</section>
);
}
// app/blog/[categorySlug]/[documentSlug]/page.tsx
import { fetchDocumentBySlug } from '@skyscribe-sdk/core';
import { scribe, AUTHOR, PUBLICATION_URL } from '@/lib/scribe';
type Props = { params: Promise<{ categorySlug: string; documentSlug: string }> };
export const generateStaticParams = scribe.generateCategoryDocumentParams;
export async function generateMetadata({ params }: Props) {
const { documentSlug } = await params;
return scribe.generateDocumentMetadata(documentSlug);
}
export default async function DocumentPage({ params }: Props) {
const { documentSlug } = await params;
const document = await fetchDocumentBySlug(AUTHOR, PUBLICATION_URL, documentSlug);
return (
<article>
<h1>{document.title}</h1>
{document.description && <p>{document.description}</p>}
<div className="scribe-content" dangerouslySetInnerHTML={{ __html: document.content }} />
</article>
);
}
If you render Documents from accounts you don't control, sanitise content first (see Rendering the HTML).
The factory's generate*Metadata functions work from the Publication record alone: title, description and the image. For canonical URLs, og:type, Twitter Cards and the Document's own cover image, fetch the Document and use documentMetadata:
import { fetchDocumentBySlug, fetchPublication } from '@skyscribe-sdk/core';
import { documentMetadata } from '@skyscribe-sdk/next';
export async function generateMetadata({ params }: Props) {
const { documentSlug } = await params;
const [document, publication] = await Promise.all([
fetchDocumentBySlug(AUTHOR, PUBLICATION_URL, documentSlug),
fetchPublication(AUTHOR, PUBLICATION_URL),
]);
const base = documentMetadata(document, publication);
return { ...base, title: `${document.title} | My Blog` };
}
publicationMetadata(publication) does the same for the home and Category pages.
Metadata has no field for the site.standard link tags, so render them in the page or a layout. React 19 (Next.js 15) moves them into the <head>:
import { standardSiteLinks } from '@skyscribe-sdk/next';
{standardSiteLinks(publication, document).map(({ rel, href }) => (
<link key={rel} rel={rel} href={href} />
))}
The site.standard spec lets apps confirm that a website belongs to a Publication by requesting /.well-known/site.standard.publication. createWellKnownHandler returns a route handler that serves the Publication's AT URI there. Add it even if you don't use Site Analytics: readers and aggregators that show site.standard content check it, and Site Analytics only shows figures once it names your Publication. A SkyScribe Publication's URL is a bare domain, so the file is always at the root, even when your Documents live under a base path.
// app/.well-known/site.standard.publication/route.ts
import { createWellKnownHandler } from '@skyscribe-sdk/next';
import { AUTHOR, PUBLICATION_URL } from '@/lib/scribe';
export const GET = createWellKnownHandler(AUTHOR, PUBLICATION_URL);
Control revalidation with Next.js's route segment config. The SDK doesn't manage it:
// Revalidate every hour
export const revalidate = 3600;
Show the Publication's owner visit figures on its Insights tab in SkyScribe (free, cookie-free):
// Once, in a client component your root layout renders
'use client';
import { SiteAnalytics } from '@skyscribe-sdk/react';
<SiteAnalytics />
Figures only appear once your website serves the Publication verification file. See the Site Analytics guide for that, privacy, and CSP.
The main types from @skyscribe-sdk/core are re-exported:
import type { StandardPublication, StandardDocument, DocumentRef, Category } from '@skyscribe-sdk/next';