Separate Your Data Layer From Your Design Layer
ButterflyPress delivers semantic intention blocks over a pure camelCase OpenAPI contract, with zero-crash renderers for Astro, React, Next.js, and Vue plus native Shadcn registries.
Three Clean Layers.Zero CMS Coupling.
Editors compose with finite semantic intentions inside Wagtail. Frontends consume normalized camelCase payloads and render them with your own design tokens.
1. Wagtail Data Layer
Semantic intention containers (Section, Split, Grid, Stack) and composable atoms with cycle-safe OpenAPI 3.0 schemas.
2. Core & Framework SDKs
Typed client, AST camelCase normalizer, XSS-safe <BpRichText>, and recursive <BlockRenderer> for Astro, React, Next.js, and Vue.
3. Shadcn Custom Registry
Copy-owned UI blocks built on shadcn/ui and shadcn-vue primitives using pure CSS variable tokens with zero hardcoded hex colors.
4. Pluggable Feature Registry
Vertical capabilities register isolated /api/v1/ endpoints, OpenAPI extensions, and StreamField blocks without polluting core CMS models.
Architectural Guarantees
- ✓ Zero CSS Classes in CMS Intentions (surface, density, proportion) replace fragile grid numbers.
- ✓ Semantic Fallback Engine New backend blocks render cleanly without crashing existing sites.
- ✓ Dual Light & Dark Tokens 20 standard Shadcn CSS variables emitted natively per theme.
- ✓ Cycle & XSS Hardened Depth-bounded recursion and sanitized HTML + action URLs.
One Headless Core, Infinite Brand Identities
Every framework adapter shares the same 30-key block registry, case compatibility shims, and Light/Dark design tokens.
@butterflypress/core
Zero-dependency HTTP client, OpenAPI-generated TypeScript types, AST camelCase normalizer, and HTML-preserving processRichText().
@butterflypress/astro
Lightweight recursive <BlockRenderer.astro />, SEO & i18n routing helpers, and Astro Shadcn Registry blocks.
@butterflypress/react & Next.js
Standalone React 18/19 renderer plus a slim Next.js adapter for RSC fetchers, Metadata API, and Draft Preview.
@butterflypress/vue
Framework-agnostic Vue 3 <BlockRenderer /> with toRaw() cycle protection and 18 shadcn-vue blocks.
Live Admin Catalog
Native Wagtail /cms/catalog/ inspector with Cotton SSR previews, Light/Dark switcher, and copyable JSON/TS guides.
Multi-Theme Showcase
Preview all 7 generic theme archetypes in Light & Dark modes side-by-side across Astro, React, and Vue.
Powering Multi-Framework Digital Platforms
From luxury hospitality sanctuaries to kinetic sports clubs and clinical portals.
"Switching from hardcoded 12-column Bootstrap layouts to ButterflyPress intention containers eliminated our CMS-to-frontend drift completely."
"Having 1:1 block parity between Astro marketing pages and React/Vue interactive apps means editors author content once and deploy everywhere."
"The Shadcn Custom Registry lets every brand own its Tailwind markup while keeping mechanical primitives like BpImage and BpRichText centralized."
Frequently Asked Questions
Everything you need to know about adopting ButterflyPress in new or existing templates.
How does ButterflyPress separate NPM SDKs from Shadcn Registry blocks? ▼
NPM packages (@butterflypress/core, astro, react, vue) own the HTTP client, types, recursive <BlockRenderer>, mechanical primitives, and neutral fallback. Visual UI blocks live in the Shadcn Registry so you own and customize the Tailwind + Shadcn markup directly in your repo.
What happens if Wagtail adds a new block before my frontend upgrades? ▼
<BlockRenderer> resolves type:variant, then type, and finally renders <SemanticBlockFallback> — preserving headings, rich text, media, actions, and nested child blocks cleanly without crashing.
Can I use Astro, React, and Vue with the exact same backend payload? ▼
Yes. Every framework adapter implements the exact same 30-key DEFAULT_BLOCK_REGISTRY, createCaseShim compatibility, and camelCase OpenAPI contract. Try the Multi-Theme Showcase to switch frameworks live on the same payload.
How do Light and Dark color schemes work across themes? ▼
butterflypress_themes emits 20 standard Shadcn CSS variables (--background, --primary, --card, --muted, --border, etc.) for both Light and Dark schemes. Blocks never hardcode hex colors.
Launch Your Next Headless Site in Minutes
Initialize the ButterflyPress Shadcn registry with one command and start rendering semantic Wagtail StreamFields across Astro, React, Next.js, or Vue.