F Foundry
Official JavaScript SDKs

Admin SDK and Frontend SDK

Foundry ships two official framework-agnostic JavaScript SDKs. The Admin SDK gives admin frontends and plugin UIs a stable client contract over the Go backend. The Frontend SDK gives JS-powered themes a stable route/content/search/navigation surface without binding them to renderer internals.

Why they exist

These SDKs are the supported client boundary for future admin frontends, JS-driven themes, and plugin UIs.

Stable UI contract

Admin frontends and themes no longer need to hand-roll fetch logic against ad hoc endpoint shapes.

Framework-agnostic

The SDKs are plain ES modules. They work from vanilla JavaScript first and can be wrapped by React, Vue, Svelte, or other frameworks later.

Capability-aware

Both SDKs expose capability discovery so consumers can ask what a given install supports instead of hard-coding assumptions.

Static and live friendly

The Frontend SDK can talk to the live /__foundry/api surface in preview/server mode and can fall back to static artifacts emitted under public/__foundry/ for built sites.

Package structure

The SDKs live in the repo under sdk/ with a small shared core and separate domain modules. 

sdk/
  core/
    errors.js
    http.js
    capabilities.js
  admin/
    client.js
    session.js
    documents.js
    media.js
    settings.js
    users.js
    themes.js
    plugins.js
    audit.js
  frontend/
    client.js
    site.js
    routes.js
    content.js
    collections.js
    navigation.js
    search.js
    media.js
    preview.js
  examples/
    admin-basic.js
    frontend-theme.js

Admin SDK

Use this for the classic admin, future React admin implementations, and plugin-provided admin UI modules.

The Admin SDK targets the authenticated admin API under <admin.path>/api. It normalizes JSON requests, CSRF handling, and common error behavior. The default admin theme now consumes this SDK instead of carrying its own private fetch layer. 

import { createAdminClient } from '/__foundry/sdk/admin/index.js';

const admin = createAdminClient({ baseURL: '/__admin' });

const session = await admin.session.get();
const capabilities = await admin.capabilities.get();
const documents = await admin.documents.list({ include_drafts: 1 });

if (capabilities.has('plugins.manage')) {
  await admin.plugins.update({ name: 'toc' });
}

Current modules: session, identity, capabilities, status, documents, media, settings, users, themes, plugins, audit, plus extension access through admin.extensions.getAdminExtensions() and settings-section metadata through admin.settings.getSections().

The default admin shell now also exposes a stable plugin page mount contract. When a plugin-defined admin page is active, the shell dispatches foundry:admin-extension-page with the page metadata, current session/capabilities, plugin settings sections, and a stable mount target id. The shell also exposes window.FoundryAdmin with the shared admin client and extension registry helpers.

Frontend SDK

Use this for JS-powered themes, hybrid server/client themes, and future headless-friendly presentation layers.

The Frontend SDK targets the public Foundry platform surface at /__foundry. In preview/server mode it uses live JSON endpoints under /__foundry/api. For built/static sites it uses generated artifacts under public/__foundry/. The default frontend theme now boots through a small SDK-based runtime at /theme/js/foundry-theme.js. 

import { createFrontendClient } from '/__foundry/sdk/frontend/index.js';

const frontend = createFrontendClient({ mode: 'auto' });

const site = await frontend.site.getInfo();
const current = await frontend.content.getCurrent();
const nav = await frontend.navigation.get('main');
const results = await frontend.search.query('foundry');

console.log(site.title, current?.title, nav.length, results.items.length);

Current modules: capabilities, site, navigation, routes, content, collections, search, media, and preview for preview-manifest access.

Capability discovery and errors

Consumers should detect what a given install supports and should get normalized failure objects back from the SDK instead of hand-parsing every failed fetch.

Admin capability discovery is exposed at <admin.path>/api/capabilities. Frontend capability discovery is exposed at /__foundry/api/capabilities and mirrored into public/__foundry/capabilities.json. Preview manifests are exposed at /__foundry/api/preview and mirrored into public/__foundry/preview.json.

The shared core includes explicit error classes for auth, validation, not-found, and unsupported operations.

Extension strategy

The SDKs are intentionally structured to absorb future platform work without forcing every UI consumer to chase internal rewrites.

  • Future admin pages, widgets, slots, and settings sections should target the Admin SDK instead of private endpoints.
  • Future React or alternate admin frontends should be thin UI layers on top of the same admin client contract.
  • Future JS-powered themes should use the Frontend SDK instead of scraping template data or relying on unstable JSON blobs.
  • Sync, storage, preview, and plugin-admin registry support can extend the existing client modules without breaking the creation story. 
document.addEventListener('foundry:admin-extension-page', async (event) => {
  const mount = document.getElementById(event.detail.mountId);
  const { client } = window.FoundryAdmin;
  const status = await client.status.get();
  mount.textContent = JSON.stringify(status, null, 2);
});

A concrete reference implementation of that mount pattern ships in sdk/examples/admin-extension-page.js.