@the-smithy/hearth

The typed client for Hearth, The Smithy's headless CMS: a site's frontend uses it to read its pages, events and settings, render SEO tags, submit forms and show live previews.

It needs API access to Hearth. Every request is made with a Hearth site's API key, so the package does nothing without a Hearth account. Developer access is by invitation: request it at hearth.thesmithy.io/developers.

Getting started

Most sites start from the starter template, which has this package set up already. For example, for a site whose address in Hearth is acme (the part after /admin/sites/ in Hearth's address bar):

pnpm create @the-smithy/hearth-site@latest acme-website --site acme

acme-website is the folder it creates. Keep @latest: pnpm otherwise skips a release in its first day.

To add it to an existing project instead:

pnpm add @the-smithy/hearth

# .env.local (never committed)
HEARTH_SITE=acme
HEARTH_API_KEY=hk_…   # Hearth → the site → API & webhooks → API keys

// lib/hearth.ts (server only: the key is secret)
import { createHearthClient } from "@the-smithy/hearth";

export const hearth = createHearthClient({
  site: process.env.HEARTH_SITE!,
  apiKey: process.env.HEARTH_API_KEY!,
});

With an AI coding assistant

The package ships llms.md, a short reference written for coding agents: point yours at node_modules/@the-smithy/hearth/llms.md. Once the key is in .env.local, the full API guide can be saved for the agent too (sites made from the starter have pnpm hearth:docs for this):

curl -H "Authorization: Bearer $HEARTH_API_KEY" https://hearth.thesmithy.io/admin/docs/api.md -o hearth-api.md

Keep hearth-api.md out of git, and the key out of chat: the agent only needs it in .env.local.

Documentation

Once you have developer access, the full documentation (every method, Next.js helpers, rendering blocks, previews, forms and webhooks) is in your Hearth account under API docs, with a Markdown version to give an AI coding assistant.

License

For use with Hearth. See LICENSE.