Skip to main content

Show Bluesky comments on Docusaurus and, too, number of likes/reposts

Integrate Bluesky comments, likes, and repost counts directly into your Docusaurus blog posts.

· 6 min read
View raw
Christophe
Markdown, WSL and Docker lover ~ Insatiable curious.
Cet article existe aussi en français — lire la version française.
This article is part of the Bluesky Docusaurus component series:

Changelog

Latest
Add real screenshots of the engagement block and describe the unified "engagement facepile" — likes, reposts and commenters are now merged into a single, deduplicated avatar stack instead of a separate likers-only row.

Show Bluesky comments on Docusaurus and, too, number of likes/reposts

⚡
TL;DR

This article is the second part of the 'Bluesky Docusaurus component' series. It enhances the component created in the first part by adding features to display Bluesky comments, likes, and repost counts directly on your Docusaurus blog. To achieve this, you'll learn how to link your blog posts to Bluesky posts using a frontmatter key, update the React component to fetch and display this information, and configure your Docusaurus site with your Bluesky handle.

In a previous article, we've seen how we can, simply said, provide a "Share the article on Bluesky".

This is not really interactive right? Let's see in this article how to make the link between a Docusaurus blog post and Bluesky.

What You'll Get​

Once wired up, every article gets a "Like, share or comment on Bluesky" button, a single engagement facepile merging likes, reposts and commenters into one deduplicated avatar stack, and the list of comments straight from your Bluesky post — right below the article, no separate comment system to host.

Here is that block, live on three different articles of this very blog, at three different levels of engagement:

http://localhost/

Engagement facepile with five people involved: likes, reposts and avatars stacked

http://localhost/

Engagement facepile together with the comments thread it links to

http://localhost/

A smaller engagement facepile: two likes, one repost

Information

Notice there's no separate "likers" row and "commenters" row: a person who both liked and commented on the post shows up as a single avatar, sorted first — that's the whole point of the facepile merge described below.

The workflow will be:

  • You publish your article on your blog,
  • You share the article on Bluesky (by using the "Share the article" feature of course),
  • You retrieve the Bluesky Record key i.e. the very last part of Bluesky post URL (something like 3lun2qjuxc22r),
  • You edit back your Docusaurus article and you add a key in your YAML front matter (the YAML block at the top of your article). The key to add is blueskyRecordKey: xxxx where xxxx is your Bluesky Record key.
  • You publish your updated article on your blog again.

So, from now, you've clearly made the link between your article and your Bluesky post.

Thanks to this link, we can:

  • Display a button "Like, share or comment on Bluesky": the visitor can then jump to your Bluesky post and like, share or comment your article,
  • Display the number of likes and reposts below your article and,
  • Display the list of comments you've received on your Bluesky post and, if none, display a Call to action area to encourage your reader to share their thoughts

In the previous article (see Create our own Docusaurus React component and provide a "Share on Bluesky" button), we've created the src/components/Bluesky/index.tsx file. Please edit that file and use this new content:

1/6 The layout of our Bluesky generic component​

Here is our new Bluesky layout for our component:

import BlueskyComments from "./comments";
import BlueskyLikes from "./likes";
import BlueskyPost from "./post";
import BlueskyShare from "./share";
import styles from "./styles.module.css";
import Translate, { translate } from "@docusaurus/Translate";
import useBlueskyEngagement, { useBlueskyRecordKey } from "./useBlueskyEngagement";
import type { BlueskyMetadata, EngagedPerson } from "./useBlueskyEngagement";
function engagementHeadline({
blueskyRecordKey,
loading,
unavailable,
engaged,
}: {
blueskyRecordKey: string | null;
loading: boolean;
unavailable: boolean;
engaged: EngagedPerson[];
}): string {
if (!blueskyRecordKey) {
return translate({
id: "bluesky.heading.share",
message: "🦋 Enjoyed this article? Share it on Bluesky",
});
}
if (loading || unavailable) {
// Same neutral copy for "still fetching" and "couldn't fetch" — never claim
// "no one reacted yet" when the truth is just "couldn't check".
return translate({
id: "bluesky.heading.join",
message: "🦋 Join the conversation on Bluesky",
});
}
if (engaged.length === 0) {
return translate({
id: "bluesky.heading.first",
message: "🦋 Be the first to react on Bluesky",
});
}
const count = engaged.length;
// Two whole sentences rather than a spliced "person is" / "people are": French agreement
// reaches further than the verb ("personne en parle" / "personnes en parlent").
return count === 1
? translate({
id: "bluesky.heading.talkingOne",
message: "🦋 1 person is already talking about this on Bluesky — join them",
})
: translate(
{
id: "bluesky.heading.talkingOther",
message:
"🦋 {count} people are already talking about this on Bluesky — join them",
},
{ count },
);
}
interface Props {
metadata: BlueskyMetadata;
}
export default function Bluesky({ metadata }: Props) {
// The frontmatter key always wins (manual override); otherwise it's looked up
// from the account's own Bluesky post history, matched against this article's
// URL — see useBlueskyRecordKey for why and how.
const { recordKey, resolving } = useBlueskyRecordKey(metadata);
const effectiveMetadata: BlueskyMetadata = {
...metadata,
frontMatter: { ...metadata.frontMatter, blueskyRecordKey: recordKey ?? undefined },
};
const stats = useBlueskyEngagement(effectiveMetadata);
// Still checking whether this article was already promoted — skip the frame
// rather than flash a "Share on Bluesky" button that may disappear a moment
// later once a match is found.
if (resolving) return null;
return (
<div className={styles.blueskyContainer}>
<span className={styles.blueskyHeadline}>
{engagementHeadline({
blueskyRecordKey: recordKey,
loading: stats.loading,
unavailable: stats.unavailable,
engaged: stats.engaged,
})}
</span>
{/* No Bluesky post found for this article: show a share button */}
<BlueskyShare metadata={effectiveMetadata} />
{/* A Bluesky post was found and its data actually loaded: show engagement UI.
Hiding BlueskyPost too when unavailable — a resolved key can point to a
post that was since deleted, and a link straight to a 404 is worse than
no link. */}
{!stats.unavailable && (
<div className={styles.blueskyEngagementRow}>
<BlueskyPost metadata={effectiveMetadata} />
<BlueskyLikes stats={stats} />
</div>
)}
<span className={styles.blueskyAccountNote}>
<Translate id="bluesky.accountNote">
{
"Requires a free Bluesky account to like, repost or comment. This block talks to Bluesky's public API directly from your browser (no cookies, no sign-in) — that means your IP address reaches Bluesky's servers just by this section loading."
}
</Translate>
</span>
<BlueskyComments metadata={effectiveMetadata} />
</div>
);
}

This component displays a Bluesky engagement section for a blog article. It fetches data about whether the article has been posted to Bluesky and how many people have engaged with it, then shows either a 'share this article' prompt or an engagement counter with likes and comments. The component carefully handles loading and error states to avoid showing misleading messages to the user.

Information

The highlighted lines are the new ones compared to the previous version of the file if you've already followed the first tutorial.

As you can see, this time, we'll foresee four components:

  • A Share button,
  • A Post button (to jump to your post on Bluesky),
  • A likes area (to show the number of likes and reposts of your post on Bluesky) and
  • An area for displaying comments you've on Bluesky

2/6 The shared data-fetching hook​

Both index.tsx (for the headline copy) and likes.tsx (for the counts and the facepile) need the same Bluesky data, so instead of fetching it twice, we centralize everything in one custom hook: useBlueskyEngagement.ts. It resolves the blueskyRecordKey (from your front matter or, if you didn't set one, by matching the article's URL against your own Bluesky post history) and fetches likes, reposts and comments in a single pass.

import { useState, useEffect } from "react";
import useDocusaurusContext from "@docusaurus/useDocusaurusContext";
import { useSourceLocaleUrls } from "@site/src/components/Blog/utils/localeUrls";
const MAX_ACTORS_PER_ENDPOINT = 20;
const FEED_CACHE_PREFIX = "bluesky-feed-cache:";
const FEED_CACHE_TTL_MS = 5 * 60 * 1000;
const MAX_FEED_PAGES = 5;
const BLOCKED_LIST_CACHE_PREFIX = "bluesky-blocked-list-cache:";
const BLOCKED_LIST_CACHE_TTL_MS = 60 * 60 * 1000; // 1 hour — list changes rarely
/** `docusaurus.config.js`'s `customFields.bluesky` — a custom field, typed `unknown` by
* Docusaurus itself, so every reader casts against this shape. */
export interface BlueskySiteConfig {
handle?: string;
/**
* AT URI of a Bluesky moderation list whose members are hidden from comments and the facepile.
* Fetched at runtime from the public API (no auth required) and cached 1 h in sessionStorage —
* adding a handle to the list takes effect on the next page load with no deploy needed.
* Create a list at bsky.app → Lists, then copy its URI (at://did:plc:…/app.bsky.graph.list/…).
*/
blockedList?: string;
/** Compile-time override: handles blocked regardless of the Bluesky list (e.g. during deploy). */
blockedHandles?: string[];
}
/** The subset of a blog post's `useBlogPost().metadata` every Bluesky file actually reads. */
export interface BlueskyMetadata {
title?: string;
permalink?: string;
frontMatter?: {
blueskyRecordKey?: string;
};
}
export type EngagementAction = "liked" | "reposted" | "commented";
export interface EngagedPerson {
did: string;
handle: string;
displayName: string;
avatar?: string;
actions: Set<EngagementAction>;
}
export interface EngagementStats {
likes: number | null;
reposts: number | null;
engaged: EngagedPerson[];
loading: boolean;
unavailable: boolean;
}
export interface RecordKeyState {
recordKey: string | null;
resolving: boolean;
}
export interface BlueskyActor {
did: string;
handle: string;
displayName?: string;
avatar?: string;
}
export interface BlueskyFacetFeature {
$type: string;
uri?: string;
}
export interface BlueskyFacet {
index: { byteStart: number; byteEnd: number };
features: BlueskyFacetFeature[];
}
export interface BlueskyPostRecord {
text: string;
facets?: BlueskyFacet[];
}
export interface BlueskyEmbedExternal {
$type: "app.bsky.embed.external#view";
external: { uri: string; title: string; thumb?: string };
}
export interface BlueskyEmbedImages {
$type: "app.bsky.embed.images#view";
images: { fullsize: string; alt?: string }[];
}
export type BlueskyEmbed = BlueskyEmbedExternal | BlueskyEmbedImages | { $type: string };
export interface BlueskyPostView {
uri: string;
indexedAt: string;
likeCount: number;
repostCount?: number;
author: BlueskyActor & { displayName: string };
record: BlueskyPostRecord;
embed?: BlueskyEmbed | null;
}
export interface BlueskyReplyNode {
post: BlueskyPostView;
replies?: BlueskyReplyNode[];
}
function flattenReplyAuthors(replies: BlueskyReplyNode[] | undefined): BlueskyActor[] {
const authors: BlueskyActor[] = [];
const walk = (arr: BlueskyReplyNode[] | undefined) => {
if (!arr) return;
for (const reply of arr) {
authors.push(reply.post.author);
walk(reply.replies);
}
};
walk(replies);
return authors;
}
function mergeEngagement(
{
likers = [],
reposters = [],
commenters = [],
}: { likers?: BlueskyActor[]; reposters?: BlueskyActor[]; commenters?: BlueskyActor[] },
ownerHandle: string | undefined,
blockedHandles: Set<string> = new Set(),
): EngagedPerson[] {
const byDid = new Map<string, EngagedPerson>();
const record = (actor: BlueskyActor | undefined, action: EngagementAction) => {
// Replying to your own readers isn't reader engagement — exclude the blog's own account.
// Also exclude any handle explicitly blocked in the site config (e.g. spammers).
if (!actor?.did || actor.handle === ownerHandle || blockedHandles.has(actor.handle))
return;
const entry = byDid.get(actor.did) || {
did: actor.did,
handle: actor.handle,
displayName: actor.displayName || actor.handle,
avatar: actor.avatar,
actions: new Set<EngagementAction>(),
};
entry.actions.add(action);
byDid.set(actor.did, entry);
};
likers.forEach((actor) => record(actor, "liked"));
reposters.forEach((actor) => record(actor, "reposted"));
commenters.forEach((actor) => record(actor, "commented"));
// People engaged in more than one way surface first — they're the strongest social proof.
return [...byDid.values()].sort((a, b) => b.actions.size - a.actions.size);
}
function normalizeUrl(url: string | null | undefined): string | null {
if (!url) return null;
return url.split("?")[0].replace(/\/+$/, "");
}
interface BlockedListResponse {
items?: { subject?: { handle?: string } }[];
cursor?: string;
}
// Fetches every handle in a Bluesky moderation list (pagination-aware) and caches
// the result in sessionStorage for 1 hour so browsing many articles doesn't re-fetch.
// Exported so BlueskyComments can share the same cache without a duplicate request.
export async function fetchBlockedList(listUri: string): Promise<Set<string>> {
const cacheKey = BLOCKED_LIST_CACHE_PREFIX + listUri;
try {
const raw = sessionStorage.getItem(cacheKey);
if (raw) {
const { timestamp, handles } = JSON.parse(raw) as {
timestamp: number;
handles: string[];
};
if (Date.now() - timestamp <= BLOCKED_LIST_CACHE_TTL_MS) return new Set(handles);
}
} catch {
/* private browsing or corrupt entry — just refetch */
}
const handles: string[] = [];
let cursor: string | undefined;
for (let page = 0; page < 10; page++) {
const params = new URLSearchParams({ list: listUri, limit: "100" });
if (cursor) params.set("cursor", cursor);
const res = await fetch(
`https://public.api.bsky.app/xrpc/app.bsky.graph.getList?${params}`,
);
if (!res.ok) break;
const data = (await res.json()) as BlockedListResponse;
for (const item of data.items ?? []) {
if (item.subject?.handle) handles.push(item.subject.handle);
}
cursor = data.cursor;
if (!cursor) break;
}
try {
sessionStorage.setItem(cacheKey, JSON.stringify({ timestamp: Date.now(), handles }));
} catch {
/* private browsing — cache miss next time, that's fine */
}
return new Set(handles);
}
type FeedIndex = Record<string, string>;
function readFeedCache(handle: string): FeedIndex | null {
try {
const raw = sessionStorage.getItem(FEED_CACHE_PREFIX + handle);
if (!raw) return null;
const { timestamp, urlToRecordKey } = JSON.parse(raw) as {
timestamp: number;
urlToRecordKey: FeedIndex;
};
if (Date.now() - timestamp > FEED_CACHE_TTL_MS) return null;
return urlToRecordKey;
} catch {
return null;
}
}
function writeFeedCache(handle: string, urlToRecordKey: FeedIndex): void {
try {
sessionStorage.setItem(
FEED_CACHE_PREFIX + handle,
JSON.stringify({ timestamp: Date.now(), urlToRecordKey }),
);
} catch {
// Private browsing / storage disabled — resolution still works, just uncached.
}
}
interface AuthorFeedItem {
post: {
uri: string;
record?: {
embed?: {
$type?: string;
external?: { uri?: string };
};
};
};
}
interface AuthorFeedResponse {
feed?: AuthorFeedItem[];
cursor?: string;
}
// Builds a { normalizedArticleUrl: recordKey } map from the account's own post
// history, matching on the "external" link-card embed Bluesky attaches when a
// post links out (the same card the Share button in this component produces).
// Cached per tab session so browsing several un-tagged articles doesn't re-fetch
// the whole feed each time.
async function buildFeedIndex(handle: string): Promise<FeedIndex> {
const cached = readFeedCache(handle);
if (cached) return cached;
const urlToRecordKey: FeedIndex = {};
let cursor: string | undefined;
for (let page = 0; page < MAX_FEED_PAGES; page += 1) {
const params = new URLSearchParams({
actor: handle,
limit: "100",
filter: "posts_no_replies",
});
if (cursor) params.set("cursor", cursor);
const res = await fetch(
`https://public.api.bsky.app/xrpc/app.bsky.feed.getAuthorFeed?${params}`,
);
if (!res.ok) throw new Error("Failed to fetch author feed");
const data = (await res.json()) as AuthorFeedResponse;
for (const item of data.feed || []) {
const embed = item.post?.record?.embed;
const externalUri =
embed?.$type === "app.bsky.embed.external" ? (embed.external?.uri ?? null) : null;
const normalized = normalizeUrl(externalUri);
if (normalized) urlToRecordKey[normalized] = item.post.uri.split("/").pop()!;
}
cursor = data.cursor;
if (!cursor || !data.feed?.length) break;
}
writeFeedCache(handle, urlToRecordKey);
return urlToRecordKey;
}
// Resolves the Bluesky record key for the current article. The frontmatter value
// always wins — it's the manual override needed after a slug rename, or to
// disambiguate an article re-promoted with a second post. Otherwise the key is
// looked up from the account's own post history. In a translated locale the
// article's own URL (`/fr/blog/x/`) is tried first, then the source-language one
// (`/blog/x/`): the author usually promotes only the English article, and French
// readers should join that conversation rather than see a "Share" button. A
// dedicated French post, if one exists, still wins. Never throws: any failure here
// (offline, blocked, no match found) just means no engagement UI is shown, the
// same as an article that was never promoted at all.
export function useBlueskyRecordKey(
metadata: BlueskyMetadata | undefined,
): RecordKeyState {
const { siteConfig } = useDocusaurusContext();
const blueSkyConfig = siteConfig?.customFields?.bluesky as
BlueskySiteConfig | undefined;
const frontMatterKey = metadata?.frontMatter?.blueskyRecordKey;
const { isDefaultLocale, sourceAbsoluteUrl } = useSourceLocaleUrls();
// `permalink` comes from Docusaurus and already carries the locale's baseUrl
// (`/fr/blog/x/`) — so `siteConfig.url + permalink` is correct as is and must
// NOT be prefixed again. The source URL is the reverse: strip that baseUrl,
// then resolve the rest against the source locale. Slugs are never translated,
// so the remainder is the same in both locales.
const permalink = metadata?.permalink;
const currentUrl = permalink ? normalizeUrl(`${siteConfig.url}${permalink}`) : null;
const sourceUrl =
permalink && !isDefaultLocale && permalink.startsWith(siteConfig.baseUrl)
? normalizeUrl(sourceAbsoluteUrl(permalink.slice(siteConfig.baseUrl.length)))
: null;
const [state, setState] = useState<RecordKeyState>({
recordKey: frontMatterKey || null,
resolving: !frontMatterKey,
});
useEffect(() => {
if (frontMatterKey) {
// eslint-disable-next-line react-hooks/set-state-in-effect -- mirrors a prop change (article navigation), not derivable at render time
setState({ recordKey: frontMatterKey, resolving: false });
return;
}
if (!blueSkyConfig?.handle || !currentUrl) {
setState({ recordKey: null, resolving: false });
return;
}
let cancelled = false;
(async () => {
try {
const index = await buildFeedIndex(blueSkyConfig.handle!);
if (!cancelled)
setState({
recordKey: index[currentUrl] || (sourceUrl && index[sourceUrl]) || null,
resolving: false,
});
} catch (e) {
console.error("Bluesky record key lookup failed:", e);
if (!cancelled) setState({ recordKey: null, resolving: false });
}
})();
return () => {
cancelled = true;
};
}, [frontMatterKey, blueSkyConfig?.handle, currentUrl, sourceUrl]);
return state;
}
interface LikesResponse {
likes: { actor: BlueskyActor }[];
}
interface RepostedByResponse {
repostedBy: BlueskyActor[];
}
async function fetchActors(
endpoint: "getLikes" | "getRepostedBy",
uri: string,
listKey: "likes" | "repostedBy",
): Promise<BlueskyActor[]> {
const url = `https://public.api.bsky.app/xrpc/app.bsky.feed.${endpoint}?uri=${encodeURIComponent(
uri,
)}&limit=${MAX_ACTORS_PER_ENDPOINT}`;
const res = await fetch(url);
if (!res.ok) throw new Error(`Failed to fetch ${endpoint}`);
const data = (await res.json()) as LikesResponse | RepostedByResponse;
return listKey === "likes"
? (data as LikesResponse).likes.map(({ actor }) => actor)
: (data as RepostedByResponse).repostedBy;
}
interface PostThreadResponse {
thread: {
post: { likeCount: number; repostCount: number; uri: string };
replies?: BlueskyReplyNode[];
};
}
// Shared by index.tsx (headline copy) and likes.tsx (counts + facepile) so the
// thread/likes/reposts fetches happen once per post, not once per consumer.
export default function useBlueskyEngagement(
metadata: BlueskyMetadata | undefined,
): EngagementStats {
const { siteConfig } = useDocusaurusContext();
const blueSkyConfig = siteConfig?.customFields?.bluesky as
BlueskySiteConfig | undefined;
const blueskyRecordKey = metadata?.frontMatter?.blueskyRecordKey;
const [stats, setStats] = useState<EngagementStats>({
likes: null,
reposts: null,
engaged: [],
loading: true,
unavailable: false,
});
useEffect(() => {
if (!blueskyRecordKey || !blueSkyConfig?.handle) {
// eslint-disable-next-line react-hooks/set-state-in-effect -- resets stats when the post/config identity changes; the effect also fetches below, it's not derivable at render time
setStats({
likes: null,
reposts: null,
engaged: [],
loading: false,
unavailable: false,
});
return;
}
const fetchData = async () => {
const postUri = `at://${blueSkyConfig.handle}/app.bsky.feed.post/${blueskyRecordKey}`;
const threadUrl = `https://public.api.bsky.app/xrpc/app.bsky.feed.getPostThread?uri=${encodeURIComponent(
postUri,
)}&depth=5`;
// Fetch the thread and the moderation list in parallel — neither depends on the other.
// The list is cached 1 h in sessionStorage, so after the first load it resolves instantly.
try {
const [threadRes, listBlocked] = await Promise.all([
fetch(threadUrl),
blueSkyConfig.blockedList
? fetchBlockedList(blueSkyConfig.blockedList).catch(() => new Set<string>())
: Promise.resolve(new Set<string>()),
]);
const blockedHandles = new Set([
...(blueSkyConfig.blockedHandles ?? []),
...listBlocked,
]);
const res = threadRes;
if (!res.ok) throw new Error("Failed to fetch post data");
const data = (await res.json()) as PostThreadResponse;
const { likeCount, repostCount, uri: resolvedUri } = data.thread.post;
const commenters = flattenReplyAuthors(data.thread.replies);
setStats({
likes: likeCount,
reposts: repostCount,
engaged: mergeEngagement({ commenters }, blueSkyConfig.handle, blockedHandles),
loading: false,
unavailable: false,
});
// resolvedUri carries the post's DID (getLikes/getRepostedBy return nothing for a handle-based URI)
const [likers, reposters] = await Promise.all([
likeCount > 0 ? fetchActors("getLikes", resolvedUri, "likes") : [],
repostCount > 0 ? fetchActors("getRepostedBy", resolvedUri, "repostedBy") : [],
]);
setStats((prev) => ({
...prev,
engaged: mergeEngagement(
{ likers, reposters, commenters },
blueSkyConfig.handle,
blockedHandles,
),
}));
} catch (e) {
// Offline, blocked by the visitor (ad-blocker, DNS filtering), or Bluesky
// itself down — never surface this as a JS error, just mark the data as
// unavailable so the UI doesn't claim "no one reacted yet" instead.
console.error("Error fetching Bluesky stats:", e);
setStats({
likes: null,
reposts: null,
engaged: [],
loading: false,
unavailable: true,
});
}
};
fetchData();
}, [
blueskyRecordKey,
blueSkyConfig?.handle,
blueSkyConfig?.blockedHandles,
blueSkyConfig?.blockedList,
]);
return stats;
}

This file provides utilities for integrating Bluesky social media engagement into a Docusaurus blog. It defines TypeScript interfaces for Bluesky API responses and blog metadata, exports functions to fetch blocked user lists and engagement metrics (likes, reposts, replies), and provides React hooks that resolve which Bluesky post corresponds to a blog article and fetch engagement statistics for display.

3/6 Our "Like, share or comment" button​

import Icon from "./bluesky.svg";
import styles from "./styles.module.css";
import Translate, { translate } from "@docusaurus/Translate";
import useDocusaurusContext from "@docusaurus/useDocusaurusContext";
import type { BlueskyMetadata, BlueskySiteConfig } from "./useBlueskyEngagement";
interface Props {
metadata: BlueskyMetadata;
}
export default function BlueskyPost({ metadata }: Props) {
const { siteConfig } = useDocusaurusContext();
const blueSkyConfig = siteConfig?.customFields?.bluesky as
BlueskySiteConfig | undefined;
const blueskyRecordKey = metadata?.frontMatter?.blueskyRecordKey;
if (!blueSkyConfig?.handle || !blueskyRecordKey) {
return null;
}
const postUrl = `https://bsky.app/profile/${blueSkyConfig.handle}/post/${blueskyRecordKey}`;
return (
<a
href={postUrl}
target="_blank"
rel="noopener noreferrer"
className={styles.blueskyButton}
aria-label={translate({
id: "bluesky.post.ariaLabel",
message: "See the post on Bluesky",
})}
>
{/* alt dropped: SVGProps has no such prop — was a no-op DOM attribute even before this
migration, and the link's own aria-label already names the icon. */}
<Icon className={styles.blueskyLogo} />
<Translate id="bluesky.post.label">Like, share or comment on Bluesky</Translate>
</a>
);
}

This React component renders a link to a Bluesky post. It pulls the user's Bluesky handle from the site configuration and the post identifier from the page metadata, then builds a URL and displays it as a clickable button with an icon and text. If either the handle or post ID is missing, it renders nothing instead.

4/6 Our component for getting the number of likes and reposts​

import styles from "./styles.module.css";
import { translate } from "@docusaurus/Translate";
import type {
EngagedPerson,
EngagementAction,
EngagementStats,
} from "./useBlueskyEngagement";
const MAX_AVATARS = 10;
// Bluesky facets are keyed by "liked", "reposted", "commented" — a person can carry more than one.
function describeActions(actions: Set<EngagementAction>): string {
// Each verb is translated on its own and the list is joined here. That holds in French too
// ("a aimé, a repartagé et a commenté"), which is cheaper than translating all seven
// combinations as whole sentences.
const verbs: string[] = [];
if (actions.has("liked")) {
verbs.push(translate({ id: "bluesky.likes.verbLiked", message: "liked" }));
}
if (actions.has("reposted")) {
verbs.push(translate({ id: "bluesky.likes.verbReposted", message: "reposted" }));
}
if (actions.has("commented")) {
verbs.push(translate({ id: "bluesky.likes.verbCommented", message: "commented on" }));
}
if (verbs.length === 1) return verbs[0];
const and = translate({ id: "bluesky.likes.and", message: "and" });
return `${verbs.slice(0, -1).join(", ")} ${and} ${verbs[verbs.length - 1]}`;
}
interface Props {
stats: EngagementStats;
}
export default function BlueskyLikes({ stats }: Props) {
if (stats.loading || stats.likes === null) {
return null;
}
const shown: EngagedPerson[] = stats.engaged.slice(0, MAX_AVATARS);
const extraEngaged = stats.engaged.length - shown.length;
return (
<span className={styles.blueskyPostLikes}>
<span
className={styles.blueskyCommentLikes}
title={translate(
{
id: "bluesky.likes.likesTitle",
message: "The original post has {count} likes on Bluesky",
},
{ count: stats.likes },
)}
>
{stats.likes}
</span>
<span
className={styles.blueskyCommentReposts}
title={translate(
{
id: "bluesky.likes.repostsTitle",
message: "The original post has been shared {count} times on Bluesky",
},
// Only `likes` is narrowed by the guard above; `reposts` can still be null here.
{ count: stats.reposts ?? 0 },
)}
>
{stats.reposts}
</span>
{shown.length > 0 && (
<span className={styles.blueskyLikersAvatars}>
{shown.map((person, index) => (
<a
key={person.did}
href={`https://bsky.app/profile/${person.handle}`}
target="_blank"
rel="noopener noreferrer"
className={styles.blueskyLikersAvatarLink}
style={{ zIndex: shown.length - index }}
title={translate(
{
id: "bluesky.likes.personTitle",
message: "{name} (@{handle}) {actions} this post",
},
{
name: person.displayName,
handle: person.handle,
actions: describeActions(person.actions),
},
)}
>
<img
src={person.avatar}
alt={translate(
{ id: "bluesky.avatarAlt", message: "{name}'s avatar" },
{ name: person.displayName },
)}
className={styles.blueskyLikersAvatar}
/>
</a>
))}
{extraEngaged > 0 && (
<span className={styles.blueskyLikersAvatarMore}>+{extraEngaged}</span>
)}
</span>
)}
</span>
);
}

This component displays engagement metrics from a Bluesky post—like count, repost count, and a grid of avatars from people who engaged with it. It caps the avatar display at 10 people and shows a '+N' indicator if there are more; it also translates all text for internationalization and builds readable descriptions of what each person did (liked, reposted, commented, or combinations thereof).

Note

An earlier version of this component only showed the avatars of the people who liked the post. That was misleading: a reader could see "5 likes" next to only 3 avatars, because reposters and commenters weren't counted. The current version fetches likers, reposters and commenters in parallel, merges them into a single Map keyed by the person's Bluesky did (so the same person liking and commenting only appears once), and sorts that list by number of actions — someone who liked and commented outranks someone who only liked. Up to ten avatars are shown, the rest collapse into a +N badge, and each avatar's tooltip spells out what that person actually did ("liked and commented on this post").

5/6 Retrieving all comments​

import { useState, useEffect, type ReactNode } from "react";
import styles from "./styles.module.css";
import Translate, { translate } from "@docusaurus/Translate";
import useDocusaurusContext from "@docusaurus/useDocusaurusContext";
import { fetchBlockedList } from "./useBlueskyEngagement";
import type {
BlueskyEmbed,
BlueskyMetadata,
BlueskyPostRecord,
BlueskyReplyNode,
BlueskySiteConfig,
} from "./useBlueskyEngagement";
// Bluesky facet indices are UTF-8 byte offsets, not JS string indices.
// TextEncoder/TextDecoder ensures correct slicing for non-ASCII text (emoji, accents…).
function renderPostText(record: BlueskyPostRecord, isOwner: boolean): ReactNode {
const text = record.text;
const facets = record.facets || [];
if (facets.length === 0) return text;
const encoder = new TextEncoder();
const decoder = new TextDecoder();
const bytes = encoder.encode(text);
const parts: ReactNode[] = [];
let lastIndex = 0;
facets.forEach((facet, idx) => {
const start = facet.index.byteStart;
const end = facet.index.byteEnd;
const before = decoder.decode(bytes.slice(lastIndex, start));
if (before) parts.push(before);
const linkFeature = facet.features.find(
(f) => f.$type === "app.bsky.richtext.facet#link",
);
if (linkFeature && isOwner) {
// Site owner's links are trusted — render as a clickable anchor.
parts.push(
<a
key={`link-${idx}`}
href={linkFeature.uri}
target="_blank"
rel="noopener noreferrer nofollow"
>
{decoder.decode(bytes.slice(start, end))}
</a>,
);
} else {
// Other authors' links are unvetted (spam risk).
// Render the anchor text only — the original is reachable via "View comment".
parts.push(decoder.decode(bytes.slice(start, end)));
}
lastIndex = end;
});
if (lastIndex < bytes.length) {
parts.push(decoder.decode(bytes.slice(lastIndex)));
}
return parts;
}
function renderEmbed(embed: BlueskyEmbed | null | undefined): ReactNode {
if (!embed) return null;
// Narrowed by property presence, not by `$type` equality: `BlueskyEmbed`'s catch-all
// member types `$type` as a plain `string` (any other embed kind the API can return —
// video, record quote, …), so a literal-equality check can't exclude it and `embed.external`
// wouldn't narrow.
if ("external" in embed) {
const { uri, title, thumb } = embed.external;
return (
<a
href={uri}
target="_blank"
rel="noopener noreferrer nofollow"
className={styles.blueskyCommentEmbed}
>
{thumb && <img src={thumb} alt="" className={styles.blueskyCommentEmbedThumb} />}
<div className={styles.blueskyCommentEmbedContent}>
<strong>{title}</strong>
</div>
</a>
);
}
if ("images" in embed) {
return (
<div className={styles.blueskyCommentImages}>
{embed.images.map((image, index) => (
<img
key={index}
src={image.fullsize}
alt={
image.alt ||
translate({ id: "bluesky.embeddedImage", message: "Embedded image" })
}
className={styles.blueskyCommentImage}
/>
))}
</div>
);
}
return null;
}
interface FlattenedReply extends BlueskyReplyNode {
depth: number;
}
function BlueskyComment({
reply,
ownerHandle,
}: {
reply: FlattenedReply;
ownerHandle?: string;
}) {
const isOwner = !!ownerHandle && reply.post.author.handle === ownerHandle;
const recordKey = reply.post.uri.split("/").pop();
const profileUrl = `https://bsky.app/profile/${reply.post.author.handle}`;
const commentUrl = `https://bsky.app/profile/${reply.post.author.handle}/post/${recordKey}`;
const date = new Date(reply.post.indexedAt).toLocaleString(undefined, {
year: "numeric",
month: "short",
day: "numeric",
hour: "2-digit",
minute: "2-digit",
});
return (
<div
className={styles.blueskyCommentContainer}
style={{ paddingLeft: `${1.5 + reply.depth * 1.5}rem` }}
>
<div className={`${styles.blueskyCommentHeader} mb-2 flex items-center`}>
<a href={profileUrl} target="_blank" rel="noopener noreferrer nofollow">
<img
src={reply.post.author.avatar}
alt={translate(
{ id: "bluesky.avatarAlt", message: "{name}'s avatar" },
{ name: reply.post.author.displayName },
)}
className={styles.blueskyCommentAvatar}
/>
</a>
<div className={styles.blueskyCommentAuthorInfos}>
<a
href={profileUrl}
target="_blank"
rel="noopener noreferrer nofollow"
className={styles.blueskyCommentAuthorDisplayName}
>
{reply.post.author.displayName}
</a>
<span className={styles.blueskyCommentAuthorHandle}>
@{reply.post.author.handle}
</span>
</div>
</div>
<span className={styles.blueskyCommentDate}>{date}</span>
<p className={styles.blueskyCommentText}>
{renderPostText(reply.post.record, isOwner)}
</p>
{renderEmbed(reply.post.embed)}
<div className={styles.blueskyCommentFooter}>
<span className={styles.blueskyCommentLikes}>{reply.post.likeCount}</span>
<span className={styles.blueskyCommentReposts}>
{reply.post.repostCount || 0}
</span>
<a
className={styles.blueskyCommentLink}
href={commentUrl}
target="_blank"
rel="noopener noreferrer nofollow"
>
<Translate id="bluesky.comments.view">View comment</Translate>
</a>
</div>
</div>
);
}
interface PostThreadResponse {
thread: {
replies?: BlueskyReplyNode[];
};
}
interface Props {
metadata: BlueskyMetadata;
}
export default function BlueskyComments({ metadata }: Props) {
const { siteConfig } = useDocusaurusContext();
const blueSkyConfig = siteConfig?.customFields?.bluesky as
BlueskySiteConfig | undefined;
const blueskyRecordKey = metadata?.frontMatter?.blueskyRecordKey;
const [comments, setComments] = useState<FlattenedReply[] | null>(null);
const [error, setError] = useState(false);
useEffect(() => {
if (!blueskyRecordKey || !blueSkyConfig?.handle) return;
const fetchComments = async () => {
try {
const postUri = `at://${blueSkyConfig.handle}/app.bsky.feed.post/${blueskyRecordKey}`;
const url =
"https://public.api.bsky.app/xrpc/app.bsky.feed.getPostThread?depth=5&uri=" +
encodeURIComponent(postUri);
// Fetch thread and moderation list in parallel — shares the sessionStorage cache
// with useBlueskyEngagement so the second caller resolves instantly.
const [res, listBlocked] = await Promise.all([
fetch(url),
blueSkyConfig?.blockedList
? fetchBlockedList(blueSkyConfig.blockedList).catch(() => new Set<string>())
: Promise.resolve(new Set<string>()),
]);
if (!res.ok) throw new Error("Failed to fetch post thread");
const data = (await res.json()) as PostThreadResponse;
const blocked = new Set([
...(blueSkyConfig?.blockedHandles ?? []),
...listBlocked,
]);
const allComments: FlattenedReply[] = [];
const flattenReplies = (arr: BlueskyReplyNode[] | undefined, depth: number) => {
if (!arr) return;
for (const r of arr) {
// Skip blocked handles (e.g. spammers hidden on bsky.app but still
// returned by the public API). Sub-replies are still walked so that
// legitimate replies to a spam comment remain visible.
if (!blocked.has(r.post.author.handle)) {
allComments.push({ ...r, depth });
}
if (r.replies) flattenReplies(r.replies, depth + 1);
}
};
if (data.thread?.replies) {
flattenReplies(data.thread.replies, 0);
}
setComments(allComments);
} catch (err) {
// Offline, blocked by the visitor, or Bluesky unreachable: stay silent
// rather than surface a raw error — same outcome as no comments to show.
console.error(err);
setError(true);
}
};
fetchComments();
}, [
blueskyRecordKey,
blueSkyConfig?.handle,
blueSkyConfig?.blockedHandles,
blueSkyConfig?.blockedList,
]);
if (!blueskyRecordKey || error) return null;
if (comments === null) {
return (
<p>
<Translate id="bluesky.comments.loading">Loading comments…</Translate>
</p>
);
}
const postUrl = `https://bsky.app/profile/${blueSkyConfig?.handle}/post/${blueskyRecordKey}`;
if (comments.length === 0)
return (
<p className={styles.blueskyNoCommentYet}>
<Translate id="bluesky.comments.none">
This post is waiting for its first comment.
</Translate>
&nbsp;
<a
className={styles.blueskyNoCommentYetCTA}
href={postUrl}
target="_blank"
rel="noopener noreferrer nofollow"
>
<Translate id="bluesky.comments.cta">Share your thoughts!</Translate>
</a>
</p>
);
return (
<div className={styles.blueskyCommentsContainer}>
<h3>
<Translate id="bluesky.comments.heading" values={{ count: comments.length }}>
{"💬 Comments from Bluesky ({count})"}
</Translate>
</h3>
{comments.map((reply) => (
<BlueskyComment
key={reply.post.uri}
reply={reply}
ownerHandle={blueSkyConfig?.handle}
/>
))}
</div>
);
}

This component fetches and displays comments from Bluesky (a social media platform) on a blog post. It handles rendering the comment thread with proper text formatting for links, embeds like images and external links, and filters out blocked users while preserving replies to those users. The component also manages loading states and gracefully handles errors.

6/6 Our new CSS​

.blueskyLogo {
width: 20px;
height: 20px;
}
.blueskyContainer {
margin: 2rem 0 0.5rem;
padding: 1.1rem 1.25rem 1.4rem;
border: 1px solid var(--ifm-color-emphasis-200);
border-radius: 8px;
background: var(--ifm-background-surface-color);
}
.blueskyHeadline {
display: block;
font-weight: 500;
color: var(--ifm-color-content);
margin-bottom: 0.75rem;
}
.blueskyAccountNote {
display: block;
margin-top: 0.6rem;
font-size: smaller;
color: var(--ifm-color-emphasis-600);
}
.blueskyCommentsContainer {
border: 1px solid var(--ifm-color-emphasis-200);
margin-top: 1rem;
padding: 0.4rem 0.9rem;
margin-bottom: 1.25rem;
}
.blueskyCommentContainer {
margin-bottom: 1rem;
background-color: var(--ifm-color-emphasis-100);
padding: 0.8rem;
border-radius: 6px;
border-left: 2px solid var(--ifm-color-emphasis-300);
color: var(--ifm-font-color-base);
}
.blueskyCommentHeader {
display: flex;
align-items: center;
gap: 10px;
}
.blueskyCommentAuthorInfos {
display: flex;
flex-direction: column;
}
.blueskyCommentAvatar {
width: 32px;
height: 32px;
border-radius: 50%;
margin-right: 0.5rem;
}
.blueskyCommentAuthorDisplayName {
margin: 0;
font-weight: bold;
}
.blueskyCommentAuthorHandle {
margin: 0;
font-size: smaller;
font-weight: normal;
color: var(--ifm-color-emphasis-600);
display: block;
}
.blueskyCommentDate {
margin-left: auto;
font-size: smaller;
color: var(--ifm-color-emphasis-600);
}
.blueskyCommentText {
margin: 0.3rem 0 0;
}
.blueskyCommentLikes::before {
content: "❤️\a0";
}
.blueskyCommentLikes::after {
content: " ";
}
.blueskyCommentReposts::before {
content: "🔁\a0";
}
.blueskyCommentReposts::after {
content: " ";
}
.blueskyCommentLink::before {
content: "→\a0";
}
.blueskyCommentLink::after {
content: " ";
}
.blueskyCommentLink {
margin-right: 0.25rem;
display: inline-flex;
align-items: center;
color: var(--ifm-color-emphasis-600);
text-decoration: none;
margin-top: 0.25rem;
}
img.blueskyCommentEmbedThumb {
max-height: 250px;
}
.blueskyCommentImages {
margin-top: 0.5rem;
display: flex;
flex-wrap: wrap;
gap: 0.5rem;
}
.blueskyCommentImage {
max-width: 100%;
height: auto;
border-radius: 0.25rem;
border: 1px solid var(--ifm-color-emphasis-300);
}
.blueskyNoCommentYet {
color: var(--ifm-color-emphasis-600);
font-size: 1rem;
line-height: 1.5;
text-align: center;
padding: 20px;
background-color: var(--ifm-color-emphasis-100);
border: 1px solid var(--ifm-color-emphasis-300);
border-radius: 8px;
margin: 20px 0;
}
.blueskyNoCommentYetCTA {
font-weight: bold;
color: var(--ifm-color-primary-dark);
cursor: pointer;
text-decoration: underline;
}
[data-theme="dark"] .blueskyNoCommentYetCTA {
color: var(--ifm-color-primary-light);
}
.blueskyPostLikes {
display: inline-flex;
align-items: center;
gap: 0.4rem;
}
.blueskyLikersAvatars {
display: inline-flex;
align-items: center;
margin-left: 0.4rem;
}
.blueskyLikersAvatarLink {
margin-left: -1rem;
line-height: 0;
}
.blueskyLikersAvatarLink:first-child {
margin-left: 0;
}
.blueskyLikersAvatar {
width: 40px;
height: 40px;
border-radius: 50%;
border: 2px solid var(--ifm-background-color);
display: block;
}
.blueskyLikersAvatarMore {
margin-left: 0.4rem;
font-size: smaller;
color: var(--ifm-color-emphasis-600);
}
.blueskyEngagementRow {
display: flex;
align-items: center;
flex-wrap: wrap;
}
.blueskyButton {
align-items: center;
background-color: var(--ifm-color-emphasis-200);
border-radius: 6px;
border: 1px solid var(--ifm-color-emphasis-300);
box-shadow: none;
color: var(--ifm-font-color-base);
display: inline-flex;
font-size: 0.9rem;
font-weight: 400;
gap: 0.4rem;
margin-bottom: 0.8rem;
margin-right: 0.4rem;
padding: 0.4rem 0.9rem;
text-decoration: none;
transition:
background-color 0.2s ease,
color 0.2s ease;
}
.blueskyButton:hover {
background-color: var(--ifm-color-primary);
border-color: var(--ifm-color-primary);
color: white;
}

This stylesheet styles a Bluesky social media embed component with various sections for displaying posts, comments, user avatars, and engagement metrics. It uses CSS variables for theming to support both light and dark modes, and includes hover effects for interactive elements like buttons and links.

Update the Docusaurus configuration file​

We're almost done. In order to be able to retrieve likes, shares and comments from your Bluesky account, you have to tell the component your Bluesky handle.

You have to edit the docusaurus.config.js file and add a new section called customFields as illustrated below:

// Partial file; illustration of what you've to do
// [...]
const config = {
// [...]
customFields: {
bluesky: {
// This is the Bluesky handle as displayed in your Bluesky profile page
handle: "your-bluesky-handle",
},
}
}

This code snippet shows a configuration object that stores custom field settings, specifically for a Bluesky social media account. The user needs to replace the placeholder handle with their actual Bluesky username so the application knows which account to reference.

Danger

For sure, use yours; not mine ;-)

All Files at a Glance​

Here is the full set of files this article touched — the update to index.tsx, and the four new files (useBlueskyEngagement.ts, post.tsx, likes.tsx, comments.tsx) plus the refreshed CSS. Use the button below to copy them all at once, or download them as a ready-to-extract ZIP:

📦 Project setup: Bluesky engagement
Help

Need help here? Click the "Help" button above for setup instructions.


This article is part of the Bluesky Docusaurus component series:
Was this article helpful?
Did you try the steps in this article?
🦋 Join the conversation on BlueskyRequires a free Bluesky account to like, repost or comment. This block talks to Bluesky's public API directly from your browser (no cookies, no sign-in) — that means your IP address reaches Bluesky's servers just by this section loading.

Loading comments…