Prerender Buddy articles for Astro

Build-time content loader for articles explicitly published from Prerender Buddy (PB). PB stays the review and scheduling workspace; Astro renders the released content using your website's own pages and styles.

Pilot, version 0.1.0. Tested with Astro 7.3.5 and Node 22.23.3, including real Netlify deploy-hook builds. Requires Astro 7 and Node 22.12 or newer. Other major Astro versions have not been verified.

Install for the pilot

Install in your Astro project:

npm install @prerenderbuddy/astro

For development from source, run npm ci and npm pack in the API repository's packages/astro directory, then install the resulting tarball in your Astro project.

Connect your website

1. In PB, open the selected website's Publishing tab and choose Astro. Publishing remains restricted to the existing owner/pilot access.
2. Enter its public HTTPS website URL and article path, such as /blog/{slug}. The route in your Astro project must match this path.
3. Create a deploy hook for the correct project in your hosting provider, such as Netlify or Vercel. Enter the complete hook URL in PB's private deploy-hook field.
4. Save destination. Copy the feed URL and feed key shown once. Saving does not call the hook or deploy the website.
5. Add both values as private build environment variables in your host and local development environment:

PB_ASTRO_FEED_URL=https://api.prerenderbuddy.com/v1/publishing/astro/YOUR-PB-SITE-UUID/feed
PB_ASTRO_FEED_KEY=YOUR-WEBSITE-FEED-KEY

Do not use a PUBLIC_ prefix, put the key in a URL, commit it, or import it into browser components. The key grants read access only to released article snapshots for that PB website. It cannot generate articles, change settings or access other workspace data.

6. Add the loader and page route below. Build and deploy the website once to establish the route and build environment.
7. In PB, click Check connection. This checks that the configured destinations are public HTTPS URLs; it does not verify the host's project, permissions, build configuration or completed deployment. Publish an approved test article and inspect the host's deployment before using customer content.

Content collection

Create or update src/content.config.ts:

import { defineCollection } from 'astro:content';
import { prerenderBuddyLoader } from '@prerenderbuddy/astro';

const articles = defineCollection({
  loader: prerenderBuddyLoader({
    feedUrl: import.meta.env.PB_ASTRO_FEED_URL,
    feedKey: import.meta.env.PB_ASTRO_FEED_KEY,
  }),
});

export const collections = { articles };

The loader supplies an article schema. To extend or customize it, import articleSchema and use the resulting Zod schema in your collection. Available metadata: slug, title, excerpt, publishedAt and updatedAt. Dates are parsed as Date objects. The collection entry ID is the stable PB article UUID. Body content is available through Astro's render() function.

Article pages

Create src/pages/blog/[slug].astro, adapting the layout to your website:

---
import { getCollection, render } from 'astro:content';

export async function getStaticPaths() {
  return (await getCollection('articles')).map(article => ({
    params: { slug: article.data.slug },
    props: { article },
  }));
}

const { article } = Astro.props;
const { Content } = await render(article);
const canonical = new URL(Astro.url.pathname, Astro.site);
---
<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>{article.data.title}</title>
    <meta name="description" content={article.data.excerpt} />
    <link rel="canonical" href={canonical} />
  </head>
  <body>
    <main>
      <h1>{article.data.title}</h1>
      <article><Content /></article>
    </main>
  </body>
</html>

Set site to your real website URL in astro.config.mjs. The supplied examples/blog includes complete article and index pages for a static site. In a site using on-demand rendering, explicitly prerender these routes if using this build-time example. This package does not implement a runtime/live loader.

Keep existing collections and page templates. The integration imports content; it does not replace your design, install prerendering, or guarantee AI recommendations. Astro outputs these static articles as HTML that crawlers can read without JavaScript.

Review, publish and update

• Save and review the article in PB, then Approve article.
• Publish now → Confirm release & rebuild releases a snapshot to the website feed and sends a POST to its deploy hook. Schedule performs the same action when due.
• Drafts stay in PB. There is no “Send as CMS draft” action for Astro.
• Edit a released article in PB, review and approve it again, then choose Publish updates or schedule the update. The existing released snapshot remains in the feed until this action.
• The slug contains the original article title and full PB UUID, ensuring a stable route across edits and retries. PB preserves the first release date and records when the released content changes.
• A successful PB receipt means the host accepted the rebuild request. It does not confirm that deployment finished or that the article is live. Check the host's build logs and the resulting website. An “Open website” URL is the expected article route.
• If the hook fails or its response is lost, the snapshot remains released. The host may already have started a build. Check the host, validate the connection and retry; another build may be requested. Repeating a completed PB delivery reuses its receipt.

Archiving or deleting an article in PB excludes it from the next feed fetch. The loader removes it from the collection on the next successful build. This does not trigger a removal deployment automatically; rebuild the site to remove its static page. This package has no separate unpublish operation.

Keys and destination changes

The feed key is stored as a hash in PB; the deploy hook is encrypted. Replace feed key revokes the previous key immediately. Update the private build environment before rebuilding. Disconnect also revokes access; it does not remove already deployed pages. Changing the website URL or article path creates a new destination and feed key; earlier released snapshots are not inherited. Re-release the intended articles for the new destination.

Loader behavior

• Fetches the authenticated feed at build time; follows pagination for up to 10,000 released articles.
• Validates the entire feed and website identity before changing Astro's cached collection. Failed authorization, malformed responses or failed fetches stop the build instead of silently publishing stale cached content.
• Reuses rendered content for unchanged articles. Changed content invalidates the digest.
• Uses Astro's native Markdown renderer. Plain text is escaped and its line breaks are preserved. PB accepts titles up to 200 characters, bodies up to 100,000 characters and excerpts up to 500 characters for this destination.
• The draft body never becomes executable MDX; rendering follows your Astro Markdown configuration. Media upload and remote image management are outside this package.
• Feed requests have a 30-second timeout, refuse redirects and bound response sizes. Error messages exclude credentials and upstream response bodies.
• allowLocalhost: true permits HTTP only for loopback URLs in disposable local tests. Leave it unset on hosted projects.

Verification

# In packages/astro (Node 22.12+):
npm ci
npm test

# In the API repository, with the package built above:
PB_ASTRO_PACKAGE_DIR="$PWD/packages/astro" node --test test/astroPublishing.test.js

The full local test starts an authenticated PB feed and deploy-hook receiver using an in-memory PostgreSQL-compatible database. It invokes real Astro static builds, verifies rendered HTML, updates, archived-page removal and failed builds with invalid keys. It also covers draft/approval gates, cross-website access, pagination, hook failures, retries, scheduling, rotation and disconnects. Advisory locks are modeled in that local test.

The separate opt-in scripts/runAstroHostedAcceptance.mjs test in the API repository uses an isolated schema on actual PostgreSQL and a disposable Netlify site. It verifies session-lock concurrency, completed retries, real deploy-hook builds, live article formatting and canonical URLs, private edits, stable updates, failed builds after key revocation, key replacement and disconnect. That hosted acceptance passed on October 3, 2026. Authenticated PB browser acceptance remains a separate check before broader rollout.

Distribution keywords are withastro and astro-loader, following Astro's loader distribution guidance. This is a content loader, not an astro add integration.

Support: [email protected]