Guides
@skyscribe-sdk/social exports LikeButton, ShareButton and SubscribeButton: React components that let readers like, share and follow a Publication using their Bluesky account. SubscribeButton is the Follow button: its name comes from the record it writes, site.standard.graph.subscription. The components handle signing in through a popup, so you don't need any server code.
Buttons work on the Publication's own website
A button only works on its own Publication's website: the page it's on must be the Publication's url (with or without www.), or a SkyScribe Site showing that Publication. There's nothing to register. If the popup says the button isn't on its Publication's website, check the Publication's address in SkyScribe matches the website.
npm install @skyscribe-sdk/social
Requires React 18 or later.
The components need AT URIs: permanent identifiers for specific AT Protocol records.
LikeButton and ShareButton both need the document URI: the AT URI of the site.standard.document record, which is document.uri.site.standard.publication record, which is publication.uri.Your Document page loader should fetch both. The exact approach depends on your framework:
createDocumentRouteLoader returns the Document, with its uri. Fetch the Publication alongside it:
// app/routes/blog.$categorySlug.$documentSlug.tsx
import { createDocumentRouteLoader } from '@skyscribe-sdk/react-router-framework';
import { fetchPublication } from '@skyscribe-sdk/core';
import type { LoaderFunctionArgs } from 'react-router';
const loadDocument = createDocumentRouteLoader('alice.bsky.social', 'https://alice.bsky.social');
export async function loader(args: LoaderFunctionArgs) {
const [document, publication] = await Promise.all([
loadDocument(args),
fetchPublication('alice.bsky.social', 'https://alice.bsky.social', args.request.signal),
]);
return { document, documentUri: document.uri, publicationUri: publication.uri };
}
import { fetchDocumentBySlug, fetchPublication } from '@skyscribe-sdk/core';
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'),
]);
const documentUri = document.uri; // → LikeButton, ShareButton
const publicationUri = publication.uri; // → LikeButton, ShareButton, SubscribeButton
import { fetchDocumentBySlug, fetchPublication } from '@skyscribe-sdk/core';
const route = useRoute();
const [document, publication] = await Promise.all([
fetchDocumentBySlug('alice.bsky.social', 'https://alice.bsky.social', route.params.slug as string),
fetchPublication('alice.bsky.social', 'https://alice.bsky.social'),
]);
const documentUri = document.uri;
const publicationUri = publication.uri;
Once you have the URIs, render the components in your Document page:
import { LikeButton, ShareButton, SubscribeButton } from '@skyscribe-sdk/social';
{documentUri && (
<LikeButton
documentUri={documentUri}
publicationUri={publicationUri}
title={document.title}
/>
)}
{documentUri && (
<ShareButton
documentUri={documentUri}
publicationUri={publicationUri}
title={document.title}
/>
)}
{publicationUri && (
<SubscribeButton publicationUri={publicationUri} title="My Site" />
)}
Note
Render the buttons conditionally: documentUri only exists once the Document is fetched, and some routes (404 pages, for example) won't have one.
social.skyscribe.app, showing the Document's title (or the Publication's name, for Follow).postMessage.localStorage.Tip
If the browser blocks the postMessage, the button falls back to polling the service for up to 30 seconds.
Note
ShareButton opens a box for the reader to write their post. Pass confirm={false} (since 1.7.0) to post the title and link straight after sign-in instead. ShareButton doesn't save anything to localStorage. After a successful share it resets after 3 seconds, so the reader can share again. By default the shared post links to the current page's URL; pass canonicalUrl to link somewhere else, such as the Document's canonical URL.
All three buttons accept children to replace the default label. Pass a function to get the button's state, for different text before and after the action:
<LikeButton documentUri={documentUri} publicationUri={publicationUri} title={document.title}>
{(isLiked) => (isLiked ? "Loved it ✓" : "Did you enjoy this?")}
</LikeButton>
<ShareButton documentUri={documentUri} publicationUri={publicationUri} title={document.title}>
{(isShared) => (isShared ? "Shared! ✓" : "Share on Bluesky")}
</ShareButton>
<SubscribeButton publicationUri={publicationUri} title="My Site">
{(isSubscribed) => (isSubscribed ? "Following ✓" : "Follow this publication")}
</SubscribeButton>
Or pass a static node if the label doesn't need to change:
<LikeButton documentUri={documentUri} publicationUri={publicationUri} title={document.title}>
♥ Recommend
</LikeButton>
Note
LikeButton and SubscribeButton show their confirmed state with aria-pressed, so the button stays focusable afterwards. ShareButton is disabled during its 3-second confirmed window, because that state is temporary rather than a toggle.
Each button renders a plain, unstyled <button> with a base CSS class (scribe-atp-like-button, scribe-atp-share-button, scribe-atp-subscribe-button). The class names kept their original prefix when the packages were renamed. Pass className to add your own class:
<LikeButton
documentUri={documentUri}
publicationUri={publicationUri}
title={document.title}
className="btn btn-outline"
/>
The base class is always there, so you can also style all the buttons from your stylesheet:
.scribe-atp-like-button,
.scribe-atp-share-button,
.scribe-atp-subscribe-button {
/* shared button styles */
}
.scribe-atp-like-button[aria-pressed="true"],
.scribe-atp-subscribe-button[aria-pressed="true"] {
/* confirmed / already-actioned state */
}
.scribe-atp-share-button:disabled {
/* briefly disabled during the 3-second confirmed window */
}
All three buttons accept an onSuccess callback, called once the action completes. Use it to show a message, record an analytics event, or update the page. SubscribeButton also has onUnsubscribe.
<LikeButton
documentUri={documentUri}
publicationUri={publicationUri}
title={document.title}
onSuccess={() => toast("Thanks for the like!")}
/>
<SubscribeButton
publicationUri={publicationUri}
title="My Site"
onSuccess={() => analytics.track("subscribe")}
/>
<ShareButton
documentUri={documentUri}
publicationUri={publicationUri}
title={document.title}
onSuccess={() => toast("Article shared to Bluesky!")}
/>
With server rendering, LikeButton and SubscribeButton start in their unconfirmed state, because localStorage isn't available on the server. They read it after hydration, so a returning reader can briefly see the wrong state.
Pass defaultLiked / defaultSubscribed to set the starting state yourself and skip the localStorage read:
// app/routes/blog.$slug.tsx (React Router v7/v8 loader)
export async function loader({ request, params }: LoaderFunctionArgs) {
const cookies = parseCookies(request.headers.get("Cookie") ?? "");
return {
...articleData,
defaultLiked: cookies[`scribe:recommended:${documentUri}`] === "1",
defaultSubscribed: cookies[`scribe:subscribed:${publicationUri}`] === "1",
};
}
// In your document component:
<LikeButton
documentUri={documentUri}
publicationUri={publicationUri}
title={document.title}
defaultLiked={defaultLiked}
/>
<SubscribeButton
publicationUri={publicationUri}
title="My Site"
defaultSubscribed={defaultSubscribed}
/>
Tip
The components write liked/subscribed state to localStorage under scribe:recommended:{documentUri} and scribe:subscribed:{publicationUri}. Mirror these to a cookie (e.g. in onSuccess) so your SSR loader can read them on the next request.
SubscribeButton is a toggle. When the reader already follows the Publication, clicking it opens a popup asking them to confirm unfollowing.
After a confirmed unfollow:
localStorage is cleared for the publication.No extra props are needed: the button knows the reader's state from localStorage.
State is persisted in localStorage under:
scribe:recommended:{documentUri}: "1" when likedscribe:subscribed:{publicationUri}: "1" when subscribedThe components read this on mount, so a returning reader sees the confirmed state without signing in again.
Functions to read and set this state are exported too:
import { isRecommended, markRecommended, isSubscribed, markSubscribed, clearSubscribed } from '@skyscribe-sdk/social';
if (isRecommended(documentUri)) {
// already liked
}
markSubscribed(publicationUri); // e.g. after subscribing through your own UI
clearSubscribed(publicationUri); // e.g. after unsubscribing through your own UI
See the API reference for the full function signatures.