Add “Building a federated blog” tutorial (Astro + Bun + SQLite)#695
Open
dahlia wants to merge 42 commits intofedify-dev:mainfrom
Open
Add “Building a federated blog” tutorial (Astro + Bun + SQLite)#695dahlia wants to merge 42 commits intofedify-dev:mainfrom
dahlia wants to merge 42 commits intofedify-dev:mainfrom
Conversation
Adds the first two chapters of the new "Building a federated blog" tutorial (docs/tutorial/astro-blog.md): - Chapter 1 (Introduction): describes what we're building, the target audience, and the list of features and limitations. - Chapter 2 (Setting up): walks through installing Bun and the fedify CLI, running fedify init with the Astro + Bun + in-memory options, and verifying the project works with fedify lookup. Also adds the tutorial to the navigation in docs/.vitepress/config.mts so it appears in the sidebar. The companion example repository is at: https://github.com/fedify-dev/astro-blog Assisted-by: Claude Code:claude-sonnet-4-6
Adds chapter 3 "Building the blog" to docs/tutorial/astro-blog.md. This chapter walks through: - Defining a content collection with Astro's Content Layer API (defineCollection + glob() loader) and a Zod schema. - Creating three sample Markdown posts in src/content/posts/. - Writing a minimal Layout.astro with global CSS that readers can copy-paste without needing an external CSS framework. - Implementing the blog listing page (src/pages/index.astro) using getCollection() and the filter/sort pattern. - Implementing the individual post page using dynamic routing and the render() helper. Also includes two screenshots of the working blog UI taken with Playwright. Also excludes .playwright-mcp/ from deno fmt and git tracking. Assisted-by: Claude Code:claude-sonnet-4-6
…rial Covers the in-memory key pair store (globalThis trick for Astro HMR), the actor dispatcher returning a Person with RSA + Ed25519 keys, inbox and followers stub dispatchers, content negotiation via @fedify/astro middleware, and the HTML profile page at /users/blog. Includes a screenshot of the actor profile page and instructions for verifying with fedify lookup. Assisted-by: Claude Code:claude-sonnet-4-6
Covers using fedify tunnel to expose the local dev server publicly, the X-Forwarded-Proto fix needed so actor URIs use https://, configuring Vite's allowedHosts for tunnel hostnames, and verifying the actor is discoverable from Mastodon's search interface. Assisted-by: Claude Code:claude-sonnet-4-6
Covers Follow/Undo inbox handlers with auto-accept, storing followers in the in-memory map, returning real follower data from the followers dispatcher, and displaying the follower count on the home page. Testing instructions use ActivityPub.Academy. Assisted-by: Claude Code:claude-sonnet-4-6
Covers migrating the in-memory Map store to bun:sqlite so that key pairs and followers survive server restarts. Explains key serialization (PKCS#8/SPKI via Web Crypto) and the bun-types TypeScript integration. Assisted-by: Claude Code:claude-sonnet-4-6
Chapter 8 covers the startup post-sync mechanism: compares the Astro content collection against a SQLite `posts` table and sends Create(Article), Update(Article), or Delete(Article) activities to followers. Also explains the Article object dispatcher and how @fedify/astro handles HTML/ActivityPub content negotiation on the same URL. Also adds `twoslash` to all TypeScript code blocks in Chapters 4–7 and `// @noErrors` where imports cannot be resolved in the VitePress context. Assisted-by: Claude Code:claude-sonnet-4-6
Covers handling Create/Update/Delete(Note) inbox activities, verifying the inReplyTo points at a local Article, and displaying stored comments below each post page. Includes XSS warning about rendering remote HTML. Assisted-by: Claude Code:claude-sonnet-4-6
…rial Chapter 10 covers: HTML sanitization for comment XSS prevention, Update(Person) for profile changes, Delete(Article) for deleted posts, image attachments, and Fly.io deployment notes. Also records the new tutorial in CHANGES.md under the 2.2.0 unreleased Docs section, referencing issue fedify-dev#691. Assisted-by: Claude Code:claude-sonnet-4-6
The previous text directed readers to use a Mastodon instance without specifying one, and the screenshot was taken unauthenticated (so the searched actor didn't appear in results). ActivityPub.Academy is a sandbox Mastodon instance already used in Chapters 6 and 9, so using it throughout keeps the tutorial consistent. The screenshot (mastodon-search.png) still needs to be retaken from ActivityPub.Academy while logged in. Assisted-by: Claude Code:claude-sonnet-4-6
First-time readers may be confused by the unusual sign-up flow: no email or password is required, just a checkbox and a button. Add a brief explanation and a screenshot of the sign-up page so readers know what to expect. Assisted-by: Claude Code:claude-sonnet-4-6
Assisted-by: Claude Code:claude-sonnet-4-6
Show what the blog profile looks like on ActivityPub.Academy instead of a plain-text approximation. Assisted-by: Claude Code:claude-sonnet-4-6
…API link Convert three bold paragraph headers (Key serialization, BLOB return type, Synchronous followers) into a proper list with italic terms and colons. Also link "Web Crypto API" to its MDN page. Assisted-by: Claude Code:claude-sonnet-4-6
…Chapter 9 Assisted-by: Claude Code:claude-sonnet-4-6
Assisted-by: Claude Code:claude-sonnet-4-6
Briefly explain what Fly.io and Fly Volumes are, and frame the section as an option rather than an assumption. Assisted-by: Claude Code:claude-sonnet-4-6
- Add X-Forwarded-Host handling to the middleware code blocks (Chapter 5
and 8); previously only X-Forwarded-Proto was shown
- Add security.allowedDomains: [{}] to the astro.config.ts code block and
explain why it is required for X-Forwarded-Host to be trusted
- Remove the ORIGIN env var approach; instead instruct users to open the
tunnel URL in their browser so the first request already carries the
correct forwarded headers
- Expand the Chapter 9 "Testing with ActivityPub.Academy" section with
step-by-step instructions and four new screenshots:
- activitypub-academy-timeline.png
- activitypub-academy-reply-box.png
- activitypub-academy-reply-typed.png
- post-with-comment.png
Assisted-by: Claude Code:claude-sonnet-4-6
VitePress TOC and heading styles were broken because all chapter headings were marked as h1 with ==== underlines. Only the document title should be h1; chapter-level headings should be h2 with --- underlines, matching the convention used in docs/tutorial/microblog.md. Assisted-by: Claude Code:claude-sonnet-4-6
Prevents Hongdown's sentence-case formatter from capitalizing "bun-types" to "Bun-types" in headings. Assisted-by: Claude Code:claude-sonnet-4-6
Cross-references like "Chapter 6" are opaque without numbered headings. Replace each with an italicized, linked section title so readers can navigate directly to the referenced content. Assisted-by: Claude Code:claude-sonnet-4-6
Assisted-by: Claude Code:claude-sonnet-4-6
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughAdds a new, extensive Astro+Bun tutorial for a federated blog, registers it in docs navigation and CHANGES.md, adds Changes
Sequence Diagram(s)sequenceDiagram
participant Startup as "Startup Sync"
participant Astro as "Astro Server (actor/inbox/outbox)"
participant DB as "SQLite (blog.db)"
participant Follower as "Remote Follower Inbox"
Startup->>Astro: Read site posts & metadata
Astro->>DB: Load stored posts/follower list
Startup->>DB: Compute diffs (Create/Update/Delete)
loop For each follower
Startup->>Follower: POST Activity (Create/Update/Delete Article)
Follower-->>Startup: 2xx / error
Startup->>DB: Record delivery/result
end
sequenceDiagram
participant Remote as "Remote Actor"
participant Inbox as "Astro Inbox Route"
participant DB as "SQLite (blog.db)"
participant Renderer as "Static Post Page"
Remote->>Inbox: POST Activity (Follow / Create(Note) / Undo / Update / Delete)
Inbox->>DB: Validate, persist follower/comment changes
DB-->>Inbox: OK
Inbox->>Renderer: (on read) render comments/follower count from DB
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Possibly related issues
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
issues-auto-labeler
Bot
added
component/actor
dahlia
changed the title
Member
Author
|
@codex review |
Member
Author
|
/gemini review |
|
Codex Review: Didn't find any major issues. Another round soon, please! ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
If Codex has suggestions, it will comment; otherwise it will react with 👍. Codex can also answer questions or update the PR. Try commenting "@codex address that feedback". |
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Code Review
This pull request introduces a comprehensive tutorial on building a federated blog using Astro and Fedify, covering actor setup, follower management, SQLite persistence, and activity handling. Supporting changes include updates to the project's configuration files and changelog. The review feedback highlights two critical issues in the tutorial's code snippets: a runtime "TypeError" caused by attempting to overwrite the read-only "APIContext.request" property in Astro middleware, and a schema validation failure in the "astro.config.ts" example due to an incorrect "security.allowedDomains" configuration.
2chanhaeng
suggested changes
Apr 21, 2026
Contributor
2chanhaeng
left a comment
2chanhaeng
left a comment
There was a problem hiding this comment.
What a great tutorial! I just got a little stuck in a few sections, so making some small adjustments there might be helpful.
Astro 7 will remove the re-export of z from astro:content. Import z from astro/zod directly as the package itself recommends. Assisted-by: Claude Code:claude-sonnet-4-6
Vite's dev server does not recognize bun: protocol imports as built-in modules, so it fails to resolve bun:sqlite when a request first hits server-side code. Setting vite.ssr.external tells Vite to skip bundling this import and let Bun's native module resolver handle it instead. Assisted-by: Claude Code:claude-sonnet-4-6
- Update fedify init console output to match current prompt order and
option text (web framework → package manager → message queue →
key-value store; removes the now-absent runtime question)
- Move the Visual Studio Code section to before the project verification
steps so readers open their editor before running commands; add
recommendation for the Astro VS Code extension
- Fix code-highlight range from {9-17} to {9-18} in the astro.config.ts
example so the full vite block is highlighted
- Add explicit import instructions before the setObjectDispatcher code
block so readers know to import Article and getCollection
Assisted-by: Claude Code:claude-sonnet-4-6
Fedify CLI 2.1.8 generates Astro+Bun projects using the @nurodev/astro-bun adapter and bunx --bun scripts instead of @astrojs/node and plain bunx. Running Astro under Bun's native runtime lets Vite resolve bun: imports directly, so the vite.ssr.external workaround for bun:sqlite added in the previous commit is no longer needed and has been removed. Also update the deployment note to refer to the @nurodev/astro-bun adapter instead of @astrojs/node. Assisted-by: Claude Code:claude-sonnet-4-6
Astro's hot-module reload does not reliably re-register Fedify's inbox listeners when src/federation.ts changes. The first Follow arriving against a stale federation object gets rejected with "Unsupported activity type: Follow," even though the code on disk is correct. A clean restart rebuilds the federation object and fixes the issue. Add a WARNING right after the federation.ts update explaining the HMR caveat (applying to later chapters too), and a matching IMPORTANT note at the ActivityPub.Academy testing step so readers do a clean restart before sending the first Follow. Assisted-by: Claude Code:claude-sonnet-4-6
Contributor
|
Pre-release has been published for this pull request: Packages
DocumentationThe docs for this pull request have been published: |
issues-auto-labeler
Bot
added
component/actor
dahlia
removed
component/federation
sij411
reviewed
Apr 22, 2026
The previous wording said \"the LogTape configuration we defined in Setting up the development environment,\" which suggested the reader had written it during an earlier step. In fact, fedify init generates src/logging.ts with sane defaults, and the setup chapter never asks the reader to write logging code. Reword to make it clear the file was scaffolded by fedify init and drop the misleading back-link. Assisted-by: Claude Code:claude-sonnet-4-6
Astro is already defined as a reference link at the top of the tutorial but was only rendered as plain text on the first Goals paragraph. Link it so readers on this page can click through to astro.build like every other mention. Assisted-by: Claude Code:claude-sonnet-4-6
sij411
approved these changes
Apr 22, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #691.
Read it at https://pr-695.fedify.pages.dev/tutorial/astro-blog.
Background
The existing microblog tutorial demonstrates building a multi-user social server with Hono and Node.js. This new tutorial covers a different workflow: layering ActivityPub federation onto a content-first blog where posts are authored as static Markdown files in Astro content collections and served via Astro's server-side rendering (SSR) mode.
The target audience is developers who already have a blog (or want one) and want to make it federable—not ActivityPub implementors building a general-purpose social server.
What's included
A new end-to-end tutorial at docs/tutorial/astro-blog.md (≈ 2,900 lines, 10 chapters) and a companion example project at https://github.com/fedify-dev/astro-blog, with each chapter corresponding to a tagged commit in the example repo.
The tutorial covers:
fedify initand Astro's content collectionsPersonactor with Ed25519 + RSA-PKCS1-v1.5 key pairsFollow/Undo(Follow)inbox handlers and a followers collectionMaptobun:sqlitefor key pairs and followerspostsSQLite table and fans outCreate(Article),Update(Article), orDelete(Article)to all followersCreate(Note)/Update(Note)/Delete(Note)inbox activities as post comments and displaying them on the post pageSupporting changes:
bun-typesadded toproper_nounsin .hongdown.toml.playwright-mcp/**added tofmt.excludein deno.json (Playwright MCP auto-generates screenshots into this directory; they should not be reformatted bydeno fmt).playwright-mcp/added to .gitignore for the same reason