API reference
Loader factories and meta helpers for React Router v7/v8 framework mode. Install with npm install @skyscribe-sdk/react-router-framework. See the React Router guide for walkthroughs.
createPublicationLoaderfunction createPublicationLoader(
author: string,
publicationUrl: string,
deps?: { fetchPublication?: typeof fetchPublication }
): (args: LoaderFunctionArgs) => Promise<StandardPublication>
Returns a React Router loader that fetches a Publication. It passes request.signal through, so the fetch is cancelled if the visitor navigates away.
| Parameter | Type | Description |
|---|---|---|
author | string | Author handle or DID |
publicationUrl | string | The Publication's canonical HTTPS URL, e.g. "https://alice.bsky.social" |
deps.fetchPublication | function | Optional. Replaces the fetch function, for testing |
// app/routes/blog.tsx
export const loader = createPublicationLoader('alice.bsky.social', 'https://alice.bsky.social');
createDocumentRouteLoaderfunction createDocumentRouteLoader(
author: string,
publicationUrl: string,
slugParam?: string,
deps?: { fetchDocumentBySlug?: typeof fetchDocumentBySlug }
): (args: LoaderFunctionArgs) => Promise<StandardDocument>
Returns a React Router loader that reads the Document's slug from the route params, fetches it with fetchDocumentBySlug, and returns the StandardDocument (its uri is the AT URI). It passes request.signal through.
| Parameter | Type | Description |
|---|---|---|
author | string | Author handle or DID |
publicationUrl | string | The Publication's canonical HTTPS URL, e.g. "https://alice.bsky.social" |
slugParam | string | Optional. URL param name to read the slug from. Defaults to "documentSlug" |
deps.fetchDocumentBySlug | function | Optional. Replaces the fetch function, for testing |
// app/routes/blog.$categorySlug.$documentSlug.tsx
export const loader = createDocumentRouteLoader('alice.bsky.social', 'https://alice.bsky.social');
// custom param name:
export const loader = createDocumentRouteLoader('alice.bsky.social', 'https://alice.bsky.social', 'slug');
The loader throws an Error naming the param if it's missing (a route set-up mistake: the route segment must be :documentSlug, or pass its name as slugParam), and NotFoundError from @skyscribe-sdk/core if no published Document has that slug. Catch NotFoundError and throw a 404 Response if you want React Router's 404 handling.
createWellKnownLoaderfunction createWellKnownLoader(
author: string,
publicationUrl: string,
deps?: { resolvePublicationUri?: typeof resolvePublicationUri }
): (args: LoaderFunctionArgs) => Promise<Response>
Returns a React Router loader 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 |
deps.resolvePublicationUri | function | Optional. Replaces the lookup function, for testing |
// app/routes.ts
route(".well-known/site.standard.publication", "routes/well-known-publication.ts"),
// app/routes/well-known-publication.ts
export const loader = createWellKnownLoader('alice.bsky.social', 'https://alice.bsky.social');
documentMetafunction documentMeta(document: StandardDocument, publication: StandardPublication): MetaDescriptor[]
Returns a MetaDescriptor[] to spread into a React Router meta function: the title, canonical link, site.standard link tags, Open Graph and Twitter Card tags, and JSON-LD structured data (the same set as core's generateDocumentMeta).
| Parameter | Type | Description |
|---|---|---|
document | StandardDocument | The full Document |
publication | StandardPublication | The Publication |
import { documentMeta } from '@skyscribe-sdk/react-router-framework';
import type { Route } from './+types/blog.$categorySlug.$documentSlug';
export function meta({ loaderData }: Route.MetaArgs) {
if (!loaderData) return [{ title: 'My Blog' }];
return [
...documentMeta(loaderData.document, loaderData.publication),
{ title: `${loaderData.document.title} — My Blog` },
];
}
Spread it first, so your own { title } at the end wins in the browser tab while the Open Graph tags keep the plain Document title. See the meta tags guide.
publicationMetafunction publicationMeta(publication: StandardPublication): MetaDescriptor[]
Returns MetaDescriptor[] for a Publication's home or Category page, the same set as core's generatePublicationMeta.
| Parameter | Type | Description |
|---|---|---|
publication | StandardPublication | The Publication |
standardSiteLinksfunction standardSiteLinks(publication: StandardPublication, document?: StandardDocument): MetaDescriptor[]
Just the site.standard link tags, for routes that don't use documentMeta or publicationMeta, such as Category pages.
All three factories accept an optional deps argument, so you can pass mock functions directly instead of using vi.mock.
import { describe, it, expect, vi } from 'vitest';
import { createPublicationLoader, createDocumentRouteLoader, createWellKnownLoader } from '@skyscribe-sdk/react-router-framework';
describe('blog loaders', () => {
it('fetches the publication', async () => {
const fetchPublication = vi.fn().mockResolvedValueOnce(mockPublication);
const loader = createPublicationLoader('alice.bsky.social', 'https://alice.bsky.social', { fetchPublication });
const result = await loader({ request: new Request('https://example.com'), params: {}, context: {} });
expect(result).toEqual(mockPublication);
expect(fetchPublication).toHaveBeenCalled();
});
it('fetches a Document by slug', async () => {
const fetchDocumentBySlug = vi.fn().mockResolvedValueOnce(mockDocument);
const loader = createDocumentRouteLoader('alice.bsky.social', 'https://alice.bsky.social', 'documentSlug', { fetchDocumentBySlug });
const result = await loader({ request: new Request('https://example.com'), params: { documentSlug: 'hello' }, context: {} });
expect(result).toEqual(mockDocument);
});
});
The main types from @skyscribe-sdk/core are re-exported:
import type { StandardPublication, StandardDocument, DocumentRef, Category } from '@skyscribe-sdk/react-router-framework';
Pass a Document's uri to @skyscribe-sdk/social's buttons. See the core reference for full type definitions.
createSiteLoader, createArticleRouteLoader (still reading params.articleSlug and returning an ArticleWithUri with documentUri), siteMeta and articleMeta still work, marked @deprecated, until the next major. See Upgrading to 5.0.