@scribe-atp/react-router-framework

Loader factories for reading Scribe CMS content in React Router v7 framework mode.

Fetches content on the server, passes it to your route component via useLoaderData, and wires up request cancellation via request.signal automatically. No client-side loading states.

Not compatible with React Router SPA (library) mode. For client-rendered React, use @scribe-atp/react instead.

Installation

npm install @scribe-atp/react-router-framework

Usage

Site index route

// app/routes/blog.tsx
import { createSiteLoader } from "@scribe-atp/react-router-framework";
import { useLoaderData } from "react-router";

export const loader = createSiteLoader("alice.bsky.social", "https://alice.bsky.social");

export default function Blog() {
  const site = useLoaderData<typeof loader>();

  return (
    <ul>
      {site.groups.map((group) =>
        group.articles.map((article) => (
          <li key={article.uri}>{article.title}</li>
        ))
      )}
    </ul>
  );
}

Dynamic article route

Use createArticleRouteLoader for routes where the slug comes from URL params. It resolves the article and returns { ...article, documentUri } — the AT URI is included so you can pass it to @scribe-atp/social's LikeButton.

// app/routes/blog.$articleSlug.tsx
import { createArticleRouteLoader } from "@scribe-atp/react-router-framework";
import { useLoaderData } from "react-router";

export const loader = createArticleRouteLoader(
  "alice.bsky.social",
  "https://alice.bsky.social"
);

export default function Article() {
  const { title, content, documentUri } = useLoaderData<typeof loader>();

  return (
    <article>
      <h1>{title}</h1>
      <div dangerouslySetInnerHTML={{ __html: content }} />
    </article>
  );
}

The third argument lets you customise the route param name (defaults to "articleSlug"):

export const loader = createArticleRouteLoader("alice.bsky.social", "https://alice.bsky.social", "slug");

AT Protocol well-known route

createWellKnownLoader serves the author's publication AT URI at a /.well-known/ endpoint — required for AT Protocol client discovery:

// app/routes/well-known.ts
import { createWellKnownLoader } from "@scribe-atp/react-router-framework";

export const loader = createWellKnownLoader("alice.bsky.social", "https://alice.bsky.social");

Open Graph and Twitter Card meta tags

articleMeta and siteMeta return a MetaDescriptor[] array ready to spread into a React Router v7 meta function. They produce Open Graph and Twitter Card tags for rich link previews on Bluesky and other platforms.

import { articleMeta } from "@scribe-atp/react-router-framework";
import type { Route } from "./+types/Article";

export function meta({ loaderData }: Route.MetaArgs) {
  if (!loaderData) return [{ title: "My Blog" }];
  return [
    ...articleMeta(loaderData.article, loaderData.site),
    { title: `${loaderData.article.title} — My Blog` },
  ];
}

siteMeta covers site index and group pages:

import { siteMeta } from "@scribe-atp/react-router-framework";

export function meta({ loaderData }: Route.MetaArgs) {
  if (!loaderData) return [{ title: "My Blog" }];
  return [
    ...siteMeta(loaderData.site),
    { title: "My Blog" },
  ];
}

Both functions require the Site object from the loader — include it in your loader return if it isn't there already.

Testing

All three factory functions accept an optional deps parameter for dependency injection. Pass mock functions directly — no vi.mock needed:

import { describe, it, expect, vi } from "vitest";
import { createSiteLoader, createArticleRouteLoader } from "@scribe-atp/react-router-framework";

const makeArgs = () =>
  ({ request: new Request("https://example.com"), params: {}, context: {} }) as any;

describe("blog loaders", () => {
  it("fetches the site", async () => {
    const fetchSite = vi.fn().mockResolvedValueOnce(mockSite);
    const loader = createSiteLoader("alice.bsky.social", "https://alice.bsky.social", { fetchSite });
    const result = await loader(makeArgs());
    expect(result).toEqual(mockSite);
  });

  it("fetches an article by slug", async () => {
    const fetchArticleBySlug = vi.fn().mockResolvedValueOnce({ article: mockArticle, uri: mockUri });
    const loader = createArticleRouteLoader(
      "alice.bsky.social",
      "https://alice.bsky.social",
      "articleSlug",
      { fetchArticleBySlug }
    );
    const result = await loader({ ...makeArgs(), params: { articleSlug: "hello" } });
    expect(result).toEqual({ ...mockArticle, documentUri: mockUri });
  });
});

TypeScript types

All types from @scribe-atp/core are re-exported, plus ArticleWithUri:

import type { Site, Article, ArticleRef, SiteGroup, ArticleWithUri } from "@scribe-atp/react-router-framework";

ArticleWithUri is the return type of createArticleRouteLoader — it extends Article with documentUri: string.

License

MIT