API reference
Metadata and static-params helpers for the Next.js 13+ App Router. Install with npm install @skyscribe-sdk/next. See the Next.js guide for walkthroughs.
createScribePublicationfunction createScribePublication(author: string, publicationUrl: string)
Returns an object of async functions (below) for generateStaticParams and generateMetadata. Each one fetches the Publication itself; fetching the content for your pages is up to you, with @skyscribe-sdk/core.
| Parameter | Type | Description |
|---|---|---|
author | string | Author handle or DID |
publicationUrl | string | The Publication's canonical HTTPS URL, e.g. "https://alice.bsky.social" |
Usage:
// lib/scribe.ts
import { createScribePublication } from '@skyscribe-sdk/next';
export const scribe = createScribePublication('alice.bsky.social', 'https://alice.bsky.social');
generateCategoryParamsgenerateCategoryParams(): Promise<{ categorySlug: string }[]>
Returns static params for a [categorySlug] route segment. Use it as generateStaticParams on a Category page.
generateDocumentParamsgenerateDocumentParams(): Promise<{ documentSlug: string }[]>
Returns static params for a single [documentSlug] segment, with no Category in the URL. Use it as generateStaticParams on a Document page with one dynamic segment. Documents without a slug are skipped.
generateCategoryDocumentParamsgenerateCategoryDocumentParams(): Promise<{ categorySlug: string; documentSlug: string }[]>
Returns static params for a [categorySlug]/[documentSlug] route. Use it as generateStaticParams on a nested Document page.
generatePublicationMetadatageneratePublicationMetadata(): Promise<Metadata>
Returns Metadata for the Publication's home page: title, description, and openGraph (with the splash image, when set). It takes no arguments, so you can assign it straight to generateMetadata.
generateCategoryMetadatagenerateCategoryMetadata(categorySlug: string): Promise<Metadata>
Returns Metadata for a Category page, titled "{Category title} — {Publication name}". It takes the slug, not Next's { params }, so call it from your own generateMetadata.
generateDocumentMetadatagenerateDocumentMetadata(documentSlug: string): Promise<Metadata>
Returns Metadata for a Document page, titled "{Document title} — {Publication name}", with the description and openGraph.images. It works from the Document's DocumentRef in the Publication, so the image is the ref's cover image, and there's no canonical URL or Twitter Card: use documentMetadata for those. Like generateCategoryMetadata, it takes the slug.
getDocumentUrigetDocumentUri(documentSlug: string): Promise<string>
Returns the AT URI of the Document with this slug, for @skyscribe-sdk/social's buttons.
createWellKnownHandlerfunction createWellKnownHandler(
author: string,
publicationUrl: string
): (request: Request) => Promise<Response>
Returns an App Router route handler that responds with the Publication's AT URI as plain text. Serve it at /.well-known/site.standard.publication, where site.standard apps look to confirm that a website belongs to a Publication.
| Parameter | Type | Description |
|---|---|---|
author | string | Author handle or DID |
publicationUrl | string | The Publication's canonical HTTPS URL |
// app/.well-known/site.standard.publication/route.ts
import { createWellKnownHandler } from '@skyscribe-sdk/next';
export const GET = createWellKnownHandler('alice.bsky.social', 'https://alice.bsky.social');
These take StandardDocument and StandardPublication objects you've already fetched, and return a Metadata object.
documentMetadatafunction documentMetadata(document: StandardDocument, publication: StandardPublication): Metadata
Returns Metadata for a Document page: title, description, a canonical URL (alternates.canonical), openGraph (type article, URL, site name, cover image) and twitter. It doesn't include structured data or the site.standard link tags, which Metadata has no field for: render generateDocumentJsonLd and standardSiteLinks in the page.
| Parameter | Type | Description |
|---|---|---|
document | StandardDocument | The full Document |
publication | StandardPublication | The Publication |
import { documentMetadata } from '@skyscribe-sdk/next';
import { fetchDocumentBySlug, fetchPublication } from '@skyscribe-sdk/core';
export async function generateMetadata({ params }: { params: Promise<{ documentSlug: string }> }) {
const { documentSlug } = await params;
const [document, publication] = await Promise.all([
fetchDocumentBySlug('alice.bsky.social', 'https://alice.bsky.social', documentSlug),
fetchPublication('alice.bsky.social', 'https://alice.bsky.social'),
]);
return documentMetadata(document, publication);
}
publicationMetadatafunction publicationMetadata(publication: StandardPublication): Metadata
Returns Metadata for a Publication's home or Category page, with a canonical URL, Open Graph and Twitter fields.
| Parameter | Type | Description |
|---|---|---|
publication | StandardPublication | The Publication |
standardSiteLinksfunction standardSiteLinks(
publication: StandardPublication,
document?: StandardDocument
): { tagName: "link"; rel: string; href: string }[]
The site.standard link tags, re-exported from core. Metadata can't hold them, so render them as <link> elements in the page or layout (React 19 moves them into the <head>):
{standardSiteLinks(publication, document).map(({ rel, href }) => (
<link key={rel} rel={rel} href={href} />
))}
generateDocumentJsonLd and generatePublicationJsonLd are re-exported too.
The main types from @skyscribe-sdk/core are re-exported:
import type { StandardPublication, StandardDocument, DocumentRef, Category } from '@skyscribe-sdk/next';
See the core reference for type definitions.
createScribeSite still works, marked @deprecated, until the next major. Its methods keep their 4.x names (generateGroupParams, generateArticleParams, generateGroupArticleParams, generateSiteMetadata, generateGroupMetadata, generateArticleMetadata) and still return { groupSlug, articleSlug } params, so rename your route folders when you switch to createScribePublication. siteMetadata and articleMetadata are deprecated aliases too. See Upgrading to 5.0.