Astro — API reference

The package has one runtime export — the ghostwritr loader factory — plus the error class and the article types. Everything is exported from the package root.

import {
  ghostwritr, // the Content Layer loader factory
  GhostwritrError, // the single error class
} from "@ghostwritr/astro";

import type {
  GhostwritrOptions, // ghostwritr() options
  Article, // the raw feed article shape
  ArticleImage, // the cover-image shape
  Author, // the byline shape
  GhostwritrErrorCode, // the error-code union
} from "@ghostwritr/astro";

ghostwritr(options)

function ghostwritr(options: GhostwritrOptions): Loader;

Returns an Astro Content Layer Loader to pass as loader on defineCollection. It validates options synchronously and throws a GhostwritrError (code CONFIG) if siteId is missing or blank. At build time the returned loader pulls the keyless static feed, change-detects against the store, and drops removed articles.

src/content.config.ts

import { defineCollection } from "astro:content";
import { ghostwritr } from "@ghostwritr/astro";

export const collections = {
  articles: defineCollection({
    loader: ghostwritr({ siteId: import.meta.env.GHOSTWRITR_SITE_ID }),
  }),
};

The loader ships a default schema (the full entry.data shape — see Collection schema). A schema on defineCollection overrides it.

GhostwritrOptions

interface GhostwritrOptions {
  siteId: string;
  staticBaseUrl?: string;
  fetch?: typeof fetch;
}

option	type	default	notes
siteId	string	— (required)	the Ghost Writr site to pull — the unguessable, keyless read capability
staticBaseUrl	string	https://feeds.ghostwritr.io	feed origin override (self-host / staging)
fetch	typeof fetch	global fetch	custom fetch — retries, caching, or a stub in tests

There is no API-key option. The siteId is the only credential; the feed is public-by-design — see Keyless reads.

GhostwritrError

class GhostwritrError extends Error {
  readonly status: number; // HTTP status, or 0 for config/network
  readonly code: GhostwritrErrorCode | null;
  readonly details?: unknown;
}

The single error type the loader throws — config errors synchronously, feed errors during the build. The same class is re-exported across @ghostwritr/feed and @ghostwritr/next, so instanceof is consistent. See Error handling for codes.

Types

• Article — the raw feed shape: timestamps are ISO-8601 strings and it carries markdown. This is the on-the-wire article, not the parsed collection entry. Re-exported from @ghostwritr/feed.
• ArticleImage — { url, alt, width: number | null, height: number | null, srcset: string | null }.
• Author — { name, slug, bio: string | null, avatarUrl: string | null, jobTitle: string | null, sameAs: string[], kind: "real" | "persona" }.
• GhostwritrErrorCode — the error-code union (CONFIG | NETWORK_ERROR | NOT_FOUND | RATE_LIMITED | SERVER_ERROR | INVALID_RESPONSE | ...), open-ended for forward compatibility.

Article vs entry.data

The parsed collection entry.data differs from the raw Article: the three timestamps are coerced to Date, the markdown is moved to entry.body / entry.rendered (not entry.data), and ghostwritrId carries the article id. The default entry.data shape is documented in Collection schema.