Statamic Bluesky Comments Laravel Package

Getting Started

This is a Statamic addon (not a standalone Laravel package) that pulls Bluesky post replies in as comments for your entries. Version 0.0.5 is a compatibility release: it adds Statamic 6 support.

1. Install via Composer into an existing Statamic site:

   composer require mitydigital/statamic-bluesky-comments
   

   Pin ^0.0.5 if you're on Statamic 6 — earlier tags (0.0.4 and below) target Statamic 5 and will not resolve against Statamic 6's constraints.

2. Publish config (the package ships a config file for the Bluesky handle/identifier and caching):

   php artisan vendor:publish --tag="statamic-bluesky-comments-config"
   

   Set your Bluesky handle/identifier there (or via .env) before rendering anything — an unconfigured handle usually surfaces as an empty comment list rather than a loud error.

3. Look here first:

   • config/statamic-bluesky-comments.php — the only knobs that matter on day one.
   • The package's Antlers tag / Blade component / fieldtype (whichever your version exposes) — check README.md at the installed tag, since the 0.0.x surface has shifted between releases.
   • vendor/mitydigital/statamic-bluesky-comments/src/ for the service provider and the class that actually hits the Bluesky API — useful when the output looks wrong.

4. First use case: add the comment output to your entry template (usually resources/views/entry.antlers.html or a partials/ file), pointing it at the entry's canonical URL or Bluesky post URI. Load one entry with real replies before wiring it into the full layout.

Implementation Patterns

Attach comments per entry, not per site. The addon resolves a Bluesky thread from a post identifier. Store that identifier on the entry (a simple text field or your own fieldtype) rather than deriving it from a slug — you'll otherwise break the link every time an entry is renamed.

Cache aggressively. Bluesky's public API is rate-limited and adds 200–800 ms to every render. Wrap the tag output in Statamic's template cache or a Cache::remember() around the fetch:

{{ cache for="15 minutes" }}
  {{ bluesky_comments :post="bluesky_uri" }}
{{ /cache }}

Clear that key on entry save via an event listener if comment freshness matters.

Render in a partial. Keep the comment markup in resources/views/partials/_comments.antlers.html and include it from entry templates. Comments are usually a progressive enhancement below the fold; isolating the partial makes it trivial to lazy-load or omit on listing pages.

Guard against missing threads. Most entries will never be posted to Bluesky. Always wrap the tag in {{ if bluesky_uri }} (or the equivalent) so entries without a discussion render nothing instead of an empty shell and a wasted API call.

Blade integration. In a Laravel/Blade context, resolve the addon's class from the container or use the published view component rather than calling the API directly — you keep the package's caching and error handling.

Testing. Use Http::fake() with a captured Bluesky app.bsky.feed.getPostThread response so your test suite doesn't depend on live API data or network access; assert your markup, not the addon's internals.

Gotchas and Tips

• 0.0.5 is a compatibility bump, not a feature release. The only change is Statamic 6 support. If you're on Statamic 5, there's no reason to move; if you're upgrading to Statamic 6, this is the minimum viable version.
• You're on a 0.0.x package. Pre-1.0 semver means the public API (tag names, config keys, fieldtype handles) can change in a patch release. Pin the exact version in composer.json and read the diff before bumping in production.
• Config cache. After editing the published config, run php artisan config:clear in development and remember config:cache in production — a stale cache is the most common cause of "it worked yesterday."
• Empty output is usually config, not code. Missing handle, wrong post URI format (at:// URI vs. web URL), or a deleted Bluesky post all render as zero comments. Log the resolved identifier before fetching.
• Rate limits and timeouts. Public Bluesky endpoints can be slow. Set a sane HTTP timeout in the config (or a global Http::timeout) so a stalled request doesn't hold your page render.
• Extension point: the published config is your primary override surface. If you need custom markup, publish the views rather than editing vendor files — vendor:publish with the package's view tag, then override in your theme.
• Watch the repo, not just Packagist. With a single maintainer and pre-1.0 versioning, breaking changes sometimes land without a changelog line beyond the PR title.