astro-loader-bluesky-posts

This package provides a Bluesky posts loader for Astro, supporting both post URLs and AT-URIs to fetch posts for use in Astro projects. Features include customizable HTML rendering, optional threaded loading, and targeted fetching of author-specific replies.

Installation

npm install -D astro-loader-bluesky-posts

Usage

To use the Astro loader, ensure Astro version ^4.14.0 || ^5.0.0. For ^4.14.0, enable the experimental content layer in astro.config.ts:

export default defineConfig({
  experimental: {
    contentLayer: true,
  },
})

In src/content/config.ts (for ^4.14.0) or src/content.config.ts (for ^5.0.0), import and configure the loader to define a new content collection:

import { defineCollection } from "astro:content"
import { BlueskyPostsLoader } from "astro-loader-bluesky-posts"

const posts = defineCollection({
  loader: BlueskyPostsLoader({
    uris: [
      'https://bsky.app/profile/bsky.app/post/3l6oveex3ii2l'
      // 'https://bsky.app/profile/did:plc:z72i7hdynmk6r22z27h6tvur/post/3l6oveex3ii2l'
      // 'at://bsky.app/app.bsky.feed.post/3l6oveex3ii2l'
      // 'at://did:plc:z72i7hdynmk6r22z27h6tvur/app.bsky.feed.post/3l6oveex3ii2l'
    ],
    // Check the configuration below
  }),
})

export const collections = { posts }

Query the content collection like any other Astro content collection to render the loaded posts:

---
import { getCollection } from "astro:content"

const posts = await getCollection("posts")
// Check the entries' Zod schema for available fields below
---

{
  posts.map(async (post) => {
    const { Content } = await render(post)
    return (
      <section>
        <Content />
        <p>{post.data.indexedAt}</p>
      </section>
    )
  })
}

To update the data, trigger a site rebuild, as the loader fetches data only at build time.

Configuration

This loader retrieves posts via the Bluesky API GET /xrpc/app.bsky.feed.getPosts and GET /xrpc/app.bsky.feed.getPostThread. Options include:

| Option (* required) | Type (default) | Description | | ------------------------ | ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | uris* | string[] | List of Bluesky post URLs or AT-URIs. | | linkTextType | 'domain-path' \| 'post-text' (default: 'post-text') | The type of text to display for links when generating renderable HTML:'domain-path': Displays the link's domain and path.'post-text': Uses the link text as shown in the tweet. | | newlineHandling | 'none' \| 'break' \| 'paragraph' (default: 'none') | The way for processing \n when generating renderable HTML:'none': Keep as is.'break': Replace consecutive \n with <br>.'paragraph': Wrap paragraphs with <p> while removing standalone \n. | | fetchThread | boolean (default: false) | Whether to fetch the post's thread including replies and parents. | | threadDepth | number (default: 1) | The depth of the descendant post tree to fetch if fetching the thread. Specifies how many levels of reply depth should be included. | | threadParentHeight | number (default: 1) | The height of the ancestor post tree to fetch if fetching the thread. Specifies how many levels of parent posts should be included. | | fetchOnlyAuthorReplies | boolean (default: false) | Whether to fetch only the post author's replies at the specified threadDepth. When true, it returns only the author's replies as a flat array, ignoring threadParentHeight and parent. |

Schema

See the source code for the Zod schema of loaded entries. Astro automatically applies this schema to generate TypeScript interfaces, enabling autocompletion and type-checking for collection queries.

To customize the schema, ensure compatibility with the loader's built-in Zod schema to prevent errors. For additional fields, consider opening an issue.

Changelog

See CHANGELOG.md for the change history of this loader.

Contribution

If you see any errors or room for improvement, feel free to open an issues or pull request . Thank you in advance for contributing! ❤️