API reference
React hooks and a content component for client-rendered React. Install with npm install @skyscribe-sdk/react. Requires React 18 or later. See the React guide for walkthroughs.
ScribeContentfunction ScribeContent(props: ScribeContentProps): JSX.Element
type ScribeContentProps = Omit<HTMLAttributes<HTMLDivElement>, "dangerouslySetInnerHTML"> & {
html: string;
embeds?: boolean; // default true
clickToLoad?: boolean; // default true
};
A thin <div> that renders a Document's HTML. It adds the scribe-content class, so @skyscribe-sdk/styles applies. It accepts all standard div attributes, and className is added to scribe-content rather than replacing it. Apart from Embeds, it renders the HTML as-is: sanitise it first if you show accounts you don't control.
It shows Embeds (videos, music, code pens, Bluesky posts and link cards) through renderEmbeds, and calls enhanceEmbeds for you. Videos, music and code pens show as Posters that load their player when clicked; pass clickToLoad={false} to load every player with the page. Bluesky posts grow to their real height. Pass embeds={false} to leave Embeds as the links they're stored as.
import { ScribeContent } from "@skyscribe-sdk/react";
import "@skyscribe-sdk/styles";
<ScribeContent html={document.content} />
// With an extra class
<ScribeContent html={document.content} className={styles.articleBody} />
See the @skyscribe-sdk/styles reference for theming and the full list of styled elements.
SiteAnalyticsfunction SiteAnalytics(props: { disabled?: boolean }): null
Adds the Site Analytics beacon to the page after it renders. Render it once, in your root layout; it renders nothing itself and works with or without server rendering. disabled leaves the beacon out.
import { SiteAnalytics } from "@skyscribe-sdk/react";
<SiteAnalytics />
usePublicationfunction usePublication(author: string, publicationUrl: string): UsePublicationResult
interface UsePublicationResult {
publication: StandardPublication | null;
loading: boolean;
error: Error | null;
}
Fetches a Publication on mount, and again whenever author or publicationUrl changes. Aborts the in-flight request on unmount and when the arguments change.
| Parameter | Type | Description |
|---|---|---|
author | string | Author handle or DID |
publicationUrl | string | The Publication's canonical HTTPS URL, e.g. "https://alice.bsky.social" |
While loading, publication is null and loading is true. On error, publication stays null and error is set. A cancelled request (AbortError) doesn't set error.
useDocumentBySlugfunction useDocumentBySlug(
author: string,
publicationUrl: string,
documentSlug: string
): UseDocumentBySlugResult
interface UseDocumentBySlugResult {
document: StandardDocument | null; // document.uri is its AT URI
loading: boolean;
error: Error | null;
}
Looks a Document up by its slug in the Publication at publicationUrl (using fetchDocumentBySlug). Fetches on mount and again whenever the arguments change, aborting the previous request.
| Parameter | Type | Description |
|---|---|---|
author | string | Author handle or DID |
publicationUrl | string | The Publication's canonical HTTPS URL |
documentSlug | string | The Document's slug, as in its URL |
If no published Document has that slug, error is a NotFoundError.
useDocumentfunction useDocument(author: string, rkey: string): UseDocumentResult
interface UseDocumentResult {
document: StandardDocument | null;
loading: boolean;
error: Error | null;
}
Fetches a Document by its record key (rkey) on mount, and again whenever the arguments change. Aborts on unmount and when the arguments change.
| Parameter | Type | Description |
|---|---|---|
author | string | Handle or DID of the account the Document is stored in |
rkey | string | The Document's record key |
Take both from a DocumentRef: the account is ref.uri.split('/')[2] and the rkey is slugFromUri(ref.uri). Don't pass a slug: it only finds very old Documents. With a slug, use useDocumentBySlug.
The main types from @skyscribe-sdk/core are re-exported:
import type { StandardPublication, StandardDocument, DocumentRef, Category, UseDocumentBySlugResult } from '@skyscribe-sdk/react';
See the core reference for type definitions.
useSite (returning { site }), useArticle ({ article }) and useArticleBySlug ({ article, uri }) still work, marked @deprecated, until the next major. See Upgrading to 5.0.