Rich Text

By default, when you create a post, @skyware/bot parses your post’s text to identify any mentions, hashtags, and URLs. However, in some cases, you may want more control over how a post is displayed. The RichText class provides a convenient interface for constructing a post containing rich text.

Usage

To start, import the RichText class from @skyware/bot:

import { class RichTextBuilder for constructing Bluesky rich textsRichText } from "@skyware/bot";

You can then build a rich text string as follows:

const const richText: RichTextrichText = new new RichText(): RichTextBuilder for constructing Bluesky rich textsRichText()
    .RichtextBuilder.addText(substr: string): RichTextAdd plain text to the rich text
@paramsubstr The plain text@returnsThe builder instance, for chainingaddText("Hey, check out this library: ")
    .RichtextBuilder.addLink(substr: string, uri: string): RichTextAdd link to the rich text
@paramsubstr Text of the link@paramuri Valid URL, for example:https://example.com@returnsThe builder instance, for chainingaddLink("skyware.js.org", "https://skyware.js.org")
    .RichtextBuilder.addText(substr: string): RichTextAdd plain text to the rich text
@paramsubstr The plain text@returnsThe builder instance, for chainingaddText("! ")
    .RichtextBuilder.addTag(tag: string): RichTextAdd inline hashtag to the rich text
@paramtag The tag, without the pound prefix@returnsTHe builder instance, for chainingaddTag("#atdev");

await const bot: Botbot.Bot.post(payload: PostPayload, options?: BotPostOptions): Promise<PostReference>Create a post.
@parampayload The post payload.@paramoptions Optional configuration.@returnsA reference to the created post.post({ PostPayload.text: string | RichTextThe post text. Can be a string or a RichText instance containing facets.text: const richText: RichTextrichText })

You’ll notice that the Bot#post method can accept either RichText or a string. Your post will look something like:

A post by user @skyware.js.org with the text "Hey, check out this library: skyware.js.org! #atdev". The link and the hashtag are highlighted blue.

Mentions

When you’re manually constructing RichText, mentioning a user requires you to know the user’s handle and DID. You can then use the .addMention method to add a mention to your post:

const const richText: RichTextrichText = new new RichText(): RichTextBuilder for constructing Bluesky rich textsRichText()
    .RichtextBuilder.addText(substr: string): RichTextAdd plain text to the rich text
@paramsubstr The plain text@returnsThe builder instance, for chainingaddText("Hey, ")
    .RichtextBuilder.addMention(substr: string, did: At.DID): RichTextMentions a user in rich text
@paramsubstr Text of the mention, this is usually in the form of @handle@paramdid Valid DID, for example: did:plc:ia76kvnndjutgedggx2ibrem@returnsThe builder instance, for chainingaddMention("@skyware.js.org", "did:plc:ith6w2xyj2qy3rcvmlsem6fz")
    .RichtextBuilder.addText(substr: string): RichTextAdd plain text to the rich text
@paramsubstr The plain text@returnsThe builder instance, for chainingaddText("!");

await const bot: Botbot.Bot.post(payload: PostPayload, options?: BotPostOptions): Promise<PostReference>Create a post.
@parampayload The post payload.@paramoptions Optional configuration.@returnsA reference to the created post.post({ PostPayload.text: string | RichTextThe post text. Can be a string or a RichText instance containing facets.text: const richText: RichTextrichText })

Note that the DID provided could differ from the mentioned handle — a mention is really just a hyperlink! Use this power for good.

Hyperlinks

Speaking of hyperlinks, mentions aren’t the only way to have text act as a link. The .addLink method we previously used can also take two parameters: text and a URL.

const const richText: RichTextrichText = new new RichText(): RichTextBuilder for constructing Bluesky rich textsRichText()
    .RichtextBuilder.addText(substr: string): RichTextAdd plain text to the rich text
@paramsubstr The plain text@returnsThe builder instance, for chainingaddText("Hey, check out ")
    .RichtextBuilder.addLink(substr: string, uri: string): RichTextAdd link to the rich text
@paramsubstr Text of the link@paramuri Valid URL, for example:https://example.com@returnsThe builder instance, for chainingaddLink("Skyware", "https://skyware.js.org")
    .RichtextBuilder.addText(substr: string): RichTextAdd plain text to the rich text
@paramsubstr The plain text@returnsThe builder instance, for chainingaddText("!");

await const bot: Botbot.Bot.post(payload: PostPayload, options?: BotPostOptions): Promise<PostReference>Create a post.
@parampayload The post payload.@paramoptions Optional configuration.@returnsA reference to the created post.post({ PostPayload.text: string | RichTextThe post text. Can be a string or a RichText instance containing facets.text: const richText: RichTextrichText })

A post by user @skyware.js.org with the text "Hey, check out Skyware!". The word "Skyware" is highlighted blue.

Plain text

As mentioned before, in most cases you won’t need to use the RichText builder, as methods like post and reply will automatically parse your text. However, if you do want to provide facets manually — say, copied from another post — you can provide the facets option:

await const bot: Botbot.Bot.post(payload: PostPayload, options?: BotPostOptions): Promise<PostReference>Create a post.
@parampayload The post payload.@paramoptions Optional configuration.@returnsA reference to the created post.post({ PostPayload.text: string | RichtextBuilderThe post text. Can be a string or a RichText instance containing facets.text: const otherPost: PostotherPost.Post.text: stringThe post text.text, PostPayload.facets?: (Facet | AppBskyRichtextFacet.Main)[] | undefinedA facet represents a range within the post's text that has special meaning
(e.g. mentions, links, tags). Prefer to use the 
{@link 
RichText
}
 class to create
posts with facets.
This will override any facets present in the 
{@link 
text
}
 property or detected automatically.facets: const otherPost: PostotherPost.Post.facets?: Facet[] | undefinedA facet represents a range within the post's text that has special meaning (e.g. mentions, links, tags).
@seeLinks, mentions, and rich text | Blueskyfacets });

Or to include no facets, pass resolveFacets: false to disable the automatic detection:

await const bot: Botbot.Bot.post(payload: PostPayload, options?: BotPostOptions): Promise<PostReference>Create a post.
@parampayload The post payload.@paramoptions Optional configuration.@returnsA reference to the created post.post({
	PostPayload.text: string | RichtextBuilderThe post text. Can be a string or a RichText instance containing facets.text: "i love the @protocol"
}, { BotPostOptions.resolveFacets?: boolean | undefinedWhether to automatically resolve facets in the post's text.

This will be ignored if the provided post data already has facets attached.
@defaulttrueresolveFacets: false });

Moving on

You may notice that adding a link to a post doesn’t automatically add an embedded preview. Learn more about that in Embeds and Images!

A post by @skyware.js.org reading "Check out this link!". The post contains an embedded link with a title, description, and preview image.