bcms-best-practices

BCMS Skills

This skill gives the AI coding agent concise, BCMS‑specific guidance and defers longer explanations to the files in references/. The agent should keep this file under roughly 500 lines and load deeper guides only when needed.

Key topics:

• Setup and client initialization (see references/​bcms-api-basics.md)
• Working with templates (see references/​templates.md)
• Entries (see references/​entries.md)
• Groups (see references/​groups.md)
• Widgets (see references/​widgets.md)
• Media (see references/​media.md)
• Properties and field types (see references/​properties.md)
• Functions and webhooks (see references/​functions-webhooks.md)
• Permissions (see references/​permissions.md)
• Framework integrations (see references/​frameworks.md)

Integration principles and defaults

• Default to the latest BCMS stack: use the latest BCMS features and the newest @thebcms/​* and @bcms-types/​* packages unless the user explicitly targets an older version.
• Model content with BCMS primitives first: prefer templates + entries as your main content model, with groups for reusable structures, widgets for reusable content blocks, and the media library for files.
• Use CLI starters when possible: for framework projects (Next, Nuxt, Astro, etc.) prefer the official @thebcms/​cli starters before hand‑rolling integration; see references/​frameworks.md.
• Render via BCMS components: in UI frameworks, prefer BCMSContentManager and BCMSImage (or their framework equivalents) to render rich text, widgets and media instead of building your own renderers.
• Always isolate secrets: read orgId, instanceId and API key credentials from environment variables, use separate keys per environment (dev/​stage/​prod) and prefer scoped keys, especially for media delivery; see references/​bcms-api-basics.md and references/​permissions.md.
• Design for localisation: when sites are multi‑lingual, use BCMS locales and model meta/content per locale; see references/​entries.md and references/​properties.md.
• Evolve schemas, don't break them: when changing content models, add or migrate fields via templates and groups; avoid destructive changes on production data; see references/​templates.md and references/​groups.md.

Patterns to avoid (and what to do instead)

• Never hard‑code API keys or use admin keys in the browser. Instead, store secrets in environment variables and use minimally scoped keys; see references/​bcms-api-basics.md and references/​permissions.md.
• Never delete templates, groups, widgets or media in production without checking impact. Always inspect usage first (group.whereIsItUsed, widget.whereIsItUsed, template.whereIsItUsed) and plan a migration path; see references/​templates.md, references/​groups.md, references/​widgets.md, and references/​media.md.
• Avoid stuffing unstructured JSON into meta or content when a property, group or widget fits. Prefer explicit properties (string, rich text, enum, pointers, media) and reusable groups/​widgets for structure; see references/​properties.md, references/​groups.md, and references/​widgets.md.
• Avoid re‑implementing rich‑text and widget rendering when BCMSContentManager is available. Use the official components (@thebcms/​components-*) with BCMSContentManager and BCMSImage, and only drop down to custom parsing when you have a clear requirement; see references/​entries.md and references/​frameworks.md.
• Avoid exposing unnecessary write capabilities to public clients. Do not use keys with create/​update/​delete rights from the frontend; keep mutations behind server‑side code or functions, and use read‑only or media‑only keys in the browser; see references/​permissions.md.
• Do not bypass webhook security. Always verify webhook signatures, check timestamps, and design idempotent handlers; see references/​functions-webhooks.md.

When to reach for which BCMS features

• Marketing, blog, or documentation sites Use templates like page, blog, doc with structured properties, groups for SEO/​author blocks, widgets for reusable sections, and the media library for images; render with BCMSContentManager and BCMSImage. See references/​templates.md, references/​entries.md, references/​groups.md, references/​widgets.md, and references/​media.md.

• Multi‑locale content Model meta and content per locale, use BCMS locales, and ensure frontends handle missing translations gracefully via types from @bcms-types/​ts. See references/​entries.md and references/​properties.md.

• Asset‑heavy or image‑driven experiences Rely on the media library, folder structure, and auto‑generated sizes; use a dedicated media API key for public delivery and BCMSImage (or equivalent) to serve optimised variants. See references/​media.md and references/​bcms-api-basics.md.

• Framework‑based frontends (Next.js, Nuxt, Astro, Gatsby, Svelte, Vite) Prefer the official BCMS starters; otherwise, follow the framework‑specific guides, using the standard Client constructor, generated types, and the appropriate @thebcms/​components-* package. See references/​frameworks.md.

Setup and Client Initialization

• Always use environment variables for secrets, never hard‑code BCMS credentials.
• Use separate API keys per environment (development, staging, production).
• Prefer scoped keys with the minimum necessary permissions.

Example client initialization (TypeScript):

import { Client } from '@thebcms/​client';

export const bcms = new Client(
  process.env.BCMS_ORG_ID!,
  process.env.BCMS_INSTANCE_ID!,
  {
    id: process.env.BCMS_API_KEY_ID!,
    secret: process.env.BCMS_API_KEY_SECRET!,
  },
  {
    injectSvg: true, // inline SVG icons into HTML
    useMemCache: true, // enable in‑memory caching
    enableSocket: false, // disable websockets when not needed
  },
);

For more, including API key structure and environment setup, see references/​bcms-api-basics.md.

Working with Templates

• Treat templates as your content types (e.g., blog, page, author).
• Use singular, descriptive names and rely on groups for reusable structures.
• Only admins (or keys with advanced rights) should create or modify templates.

Common operations:

• List all templates: await bcms.template.getAll()
• Get a template by ID or name
• Update or delete templates when refactoring content models

See references/​templates.md for naming conventions, creation guidelines and code examples.

Entries

• Entries are instances of templates (e.g., a single blog post).
• Entries usually have:
  • meta fields (title, slug, SEO, etc.)
  • content fields, often localized by language code

Example: get all entries for a blog template:

const blogPosts = await bcms.entry.getAll('blog');

Agents should be able to:

• Create, update and delete entries
• Retrieve entries by ID, slug or status
• Filter entries by template and status (e.g., draft vs. published)

See references/​entries.md for full CRUD examples and multilingual details.

Groups, Widgets and Media

• Groups are reusable structures that can be nested inside templates, widgets or other groups.
• Widgets are reusable content blocks embedded in rich‑text fields.
• Media refers to files in the BCMS media library (images, documents, etc.).

Typical operations:

• Groups:
  • bcms.group.getAll()
  • bcms.group.whereIsItUsed(groupId)
• Widgets:
  • bcms.widget.getAll()
  • bcms.widget.whereIsItUsed(widgetId)
• Media:
  • bcms.media.getAll(), bcms.media.getById(id)
  • Create folders and upload files using media API helpers

Widgets cannot currently be deleted via the SDK and must be removed via the BCMS dashboard. See references/​groups.md, references/​widgets.md and references/​media.md for concrete examples and media best‑practices.

Properties and Field Types

BCMS supports various property types used in templates, groups and widgets, including:

• String, rich‑text, number, date, boolean
• Enumeration
• Entry pointer, group pointer
• Media fields (single and multiple)

Agents should choose appropriate field types based on content modelling goals and reusability. See references/​properties.md, references/​groups.md, references/​widgets.md and references/​templates.md for details.

Permissions and API Key Scopes

• BCMS enforces granular permissions for users and API keys.
• Permissions can be:
  • Simple: broad access levels
  • Advanced: per‑resource get/​create/​update/​delete scopes
• Only admins can create templates, widgets, groups and API keys.

API keys:

• Should be scoped per template, function and media access where possible.
• Use least privilege: grant only the rights needed for the specific integration.

See references/​permissions.md for a deeper explanation and configuration examples.

Functions and Webhooks

• Functions are serverless handlers you deploy inside BCMS and call via REST.
• Webhooks notify external systems about events such as entry or media changes.

Agents should:

• Call functions using the correct URL and headers, including an API key with function permissions.
• Configure and secure webhooks by:
  • Verifying the X-Bcms-Webhook-Signature header
  • Validating timestamps to avoid replay attacks
  • Making handlers idempotent and rate‑limited

See references/​functions-webhooks.md for full examples and security notes.

Best Practices and Troubleshooting

• Prefer TypeScript and generated BCMS types (e.g., @bcms-types/​ts) where available.
• Use caching (e.g., in‑memory or application‑level) for frequently read data.
• Separate dev, staging and production environments and API keys.
• On errors, check:
  • URL correctness (org, instance, function ID)
  • API key scopes and permissions
  • Network and TLS configuration

For in‑depth guidance, always cross‑reference the official BCMS documentation from the references/ files.