Astro Integration

Overview

@sourcepress/astro bridges SourcePress and Astro. It runs at build time to sync approved content from your SourcePress backend into Astro’s content layer, generates a content.config.ts from your SourcePress schema, and registers a component registry for use in MDX pages.

Three responsibilities:

• Schema codegen — derives Astro content collection schemas from your SourcePress defineConfig schema and writes content.config.ts
• Content syncing — pulls approved content files into the Astro project at build time
• Component registry — makes SourcePress components available inside MDX

@astrojs/mdx is a hard requirement. The integration does not function without it.

Requirements

• Astro 4.x or later
• @astrojs/mdx installed and registered before @sourcepress/astro
• Node >= 20
• A configured SourcePress project with at least one collection defined via defineConfig

Usage

Install both packages:

pnpm add @sourcepress/astro @astrojs/mdx

Register the integrations in astro.config.ts. @astrojs/mdx must appear before sourcepress():

// astro.config.ts
import { defineConfig } from "astro/config";
import mdx from "@astrojs/mdx";
import sourcepress from "@sourcepress/astro";

export default defineConfig({
  integrations: [
    mdx(),
    sourcepress(),
  ],
});

With no arguments, sourcepress() reads your SourcePress config from the default location (sourcepress.config.ts at the project root).

Configuration

Pass an options object to sourcepress() to override defaults:

sourcepress({
  config: "./sourcepress.config.ts",  // path to SourcePress config file
  outDir: "./src/content",            // where synced content files are written
  contentConfig: "./src/content.config.ts", // where generated config is written
})

All fields are optional. The integration resolves paths relative to the Astro project root.

Schema Generation

At build time, @sourcepress/astro reads your SourcePress schema — defined with defineConfig, collection, field, and relation from @sourcepress/core — and generates a content.config.ts file that Astro can consume.

A SourcePress config using the core DSL:

// sourcepress.config.ts
import { defineConfig, collection, field, relation } from "@sourcepress/core";

export default defineConfig({
  collections: {
    articles: collection({
      fields: {
        title: field.string({ required: true }),
        publishedAt: field.date({ required: true }),
        summary: field.string(),
      },
      relations: {
        author: relation({ to: "authors", cardinality: "one" }),
      },
    }),
    authors: collection({
      fields: {
        name: field.string({ required: true }),
        bio: field.string(),
      },
    }),
  },
});

The integration derives Zod schemas from this config (via @sourcepress/core’s schema-to-Zod codegen) and writes the corresponding Astro collection definitions to content.config.ts. The generated file is overwritten on every build — do not edit it manually.

Content Syncing at Build Time

During the Astro build, @sourcepress/astro fetches approved content from the SourcePress backend and writes the resulting files into outDir (default: ./src/content). Files are organized by collection name, matching the structure Astro expects.

The sync runs as an Astro integration hook before the build compiles pages, so all content is available to Astro’s content layer when components and pages are rendered.

Content files written by the sync carry the provenance block recorded by SourcePress — the source knowledge files, model, eval score, and approver — preserved as frontmatter fields.

Examples

Minimal setup

// astro.config.ts
import { defineConfig } from "astro/config";
import mdx from "@astrojs/mdx";
import sourcepress from "@sourcepress/astro";

export default defineConfig({
  integrations: [
    mdx(),
    sourcepress(),
  ],
});

Custom output paths

// astro.config.ts
import { defineConfig } from "astro/config";
import mdx from "@astrojs/mdx";
import sourcepress from "@sourcepress/astro";

export default defineConfig({
  integrations: [
    mdx(),
    sourcepress({
      config: "./sourcepress.config.ts",
      outDir: "./src/content",
      contentConfig: "./src/content.config.ts",
    }),
  ],
});

Querying synced content in a page

After the build sync runs, content is available through Astro’s standard getCollection API:

---
// src/pages/articles/index.astro
import { getCollection } from "astro:content";

const articles = await getCollection("articles");
---

<ul>
  {articles.map((article) => (
    <li>
      <a href={`/articles/${article.slug}`}>{article.data.title}</a>
    </li>
  ))}
</ul>

Collection names and field names in article.data match exactly what is defined in your defineConfig schema.

Notes

• The generated content.config.ts is derived entirely from your SourcePress schema. Adding fields to a collection requires updating sourcepress.config.ts, not the generated file.
• @astrojs/mdx must be listed before sourcepress() in the integrations array. Reversing the order will cause the integration to fail.
• Content syncing requires network access to the SourcePress server at build time. Offline or CI builds must ensure the server is reachable or content files are pre-populated.
• @sourcepress/astro is part of the v0.1.0 release. APIs may change before 1.0.