JavaScript helpers

Use these helpers from Astro page frontmatter or server code. The HTTP API serves authenticated editor clients; it is not a public headless content API.

Choose a helper

Need	Helper
Generate explicit HTML bindings in a loop	bindEntry from @caretcms/core
Pass editable text through component props	editable from @caretcms/core
Read through Astro live collections	caretLoader from @caretcms/core/loader
Remove invisible binding metadata for attributes	stegaClean from @caretcms/core
Read data during a server request without registering a live collection	loadEntry, loadCollection, listCollections from @caretcms/core/runtime

Explicit bindings

---
import { bindEntry } from '@caretcms/core';
const bind = bindEntry({ collection: 'pages', id: 'home' });
---
<h1 {...bind('title')}>Welcome</h1>
<p {...bind('intro', { rich: true })}>A <strong>small</strong> site.</p>

These produce data-caret attributes. They do not fetch entry data themselves. See Inline editing.

Editable component values

---
import { editable, stegaClean } from '@caretcms/core';
const hero = await editable('pages::home::hero', {
  title: 'Welcome',
  ctaLabel: 'Contact us',
  ctaHref: '/contact',
});
---
<h1>{hero.title}</h1>
<a href={stegaClean(hero.ctaHref)}>{hero.ctaLabel}</a>

editable(key, defaults) overlays stored values and, for editor requests, encodes binding metadata in string leaves. The key is collection::id or collection::id::fieldPrefix. Objects merge by key; arrays overlay existing positions in the defaults, so this is not a collection-list query.

Keep visible editable text encoded. Clean strings used in URLs, attributes, metadata, comparisons, or other non-editable consumers with stegaClean(). Outside Caret’s request context, editable() returns defaults unchanged; for static builds use explicit bindings for the HTML bake.

Request-time content reads

---
import { loadEntry, loadCollection } from '@caretcms/core/runtime';
const home = await loadEntry('pages', 'home');
const products = await loadCollection('products');
---
<h1>{home?.title ?? 'Welcome'}</h1>
<ul>{products.map((entry) => <li>{entry.data.name}</li>)}</ul>

• loadEntry(collection, id) returns the data object or null.
• loadCollection(collection) returns entry records with id and data.
• listCollections() discovers collection names from storage.

These require Caret middleware’s active request context; they are not standalone build scripts. Reads honor the active editor overlay and configured public visibility filter, and strip private body-draft data. They do not add live-loader stega encoding or validate stored data against registered schemas. Use the live loader when you need that validation and Astro’s result/error contract.

Provider factories and contracts

Import filesystemStorage, markdownStorage, and localUploads from @caretcms/core, or Cloudflare factories from @caretcms/cloudflare. Custom integrations use defineStorageProvider, defineUploadProvider, defineIdentityProvider, and defineDeploymentProvider.

The configuration stores a runtime module and serializable options; credentials should be resolved from the runtime environment. See Configuration, Storage adapters, Permissions, and Deployment status for full examples and contracts.

@caretcms/core/contracts exposes shared binding and sanitizer contracts for integrations. The browser editor is served from the package’s static assets; applications should not import unpublished internal source files.