Frameworks
@skyscribe-sdk/react provides usePublication, useDocumentBySlug and useDocument hooks for React SPAs and client-rendered components. Each hook manages loading state, error state and request cancellation for you.
Note
For React Router v7/v8 framework (server) mode, use @skyscribe-sdk/react-router-framework instead. For the Next.js App Router, use @skyscribe-sdk/next.
npm install @skyscribe-sdk/react
Requires React 18 or later.
usePublicationimport { usePublication } from '@skyscribe-sdk/react';
function BlogIndex() {
const { publication, loading, error } = usePublication('alice.bsky.social', 'https://alice.bsky.social');
if (loading) return <p>Loading…</p>;
if (error) return <p>Error: {error.message}</p>;
if (!publication) return null;
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={`/${category.slug}/${ref.slug}`}>{ref.title}</a>
</li>
))}
</ul>
</section>
))}
</main>
);
}
useDocumentBySlugDocument pages usually have the Document's slug from the URL (/essays/my-first-post). useDocumentBySlug looks it up in the Publication and returns the Document:
import { useDocumentBySlug, ScribeContent } from '@skyscribe-sdk/react';
function DocumentPage({ slug }: { slug: string }) {
const { document, loading, error } = useDocumentBySlug(
'alice.bsky.social',
'https://alice.bsky.social',
slug,
);
if (loading) return <p>Loading…</p>;
if (error) return <p>Error: {error.message}</p>;
if (!document) return null;
return (
<article>
<h1>{document.title}</h1>
{document.description && <p>{document.description}</p>}
<ScribeContent html={document.content} />
</article>
);
}
document.uri is what @skyscribe-sdk/social's buttons need as documentUri. If no published Document has that slug, error is a NotFoundError.
useDocumentIf you already have a DocumentRef (for example while listing a Publication's Documents), useDocument skips the Publication lookup. It takes the Document's account and record key (rkey), both found in DocumentRef.uri (at://{did}/site.standard.document/{rkey}). Take the account from there rather than assuming the Publication owner's: a Document credited to a contributor can live in their account.
import { useDocument } from '@skyscribe-sdk/react';
import { slugFromUri } from '@skyscribe-sdk/core';
import type { DocumentRef } from '@skyscribe-sdk/react';
function DocumentPreview({ documentRef }: { documentRef: DocumentRef }) {
const did = documentRef.uri.split('/')[2];
const { document } = useDocument(did, slugFromUri(documentRef.uri));
// …
}
Don't pass a slug to useDocument: Documents published with current tooling have opaque rkeys, so a slug only finds very old Documents.
All three hooks re-fetch when their arguments change, and abort the in-flight request when the component unmounts.
<ScribeContent> renders a Document's HTML inside a scribe-content wrapper, ready for @skyscribe-sdk/styles. If you render Documents from accounts you don't control, sanitise the HTML first (see Rendering the HTML).
Show the Publication's owner visit figures on its Insights tab in SkyScribe (free, cookie-free):
// Once, in your root layout
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, so you rarely need to import from both packages:
import type { StandardPublication, StandardDocument, DocumentRef, Category } from '@skyscribe-sdk/react';