michtio/craftcms-claude-skills / skills/craft-site
craft-site
VerifiedCraft CMS 5 front-end Twig development — atomic design, template architecture, components, Vite buildchain. Covers atoms/molecules/organisms, props/extends/block patterns, layout chains, view routing, content builders, image presets, Tailwind named-key collections, multi-brand CSS tokens, JavaScript boundaries (Alpine/DataStar/Vue, tabs, accordions), Vite asset loading, and front-end auth (login, registration, password reset, profiles).
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 16.2 KB |
| references/atomic-design.md | markdown | 11.1 KB |
| references/atomic-patterns.md | markdown | 12.3 KB |
| references/auth-account.md | markdown | 18.1 KB |
| references/auth-flows.md | markdown | 22.5 KB |
| references/boilerplate-routing.md | markdown | 14.7 KB |
| references/component-inventory.md | markdown | 11.4 KB |
| references/composition-patterns.md | markdown | 14.5 KB |
| references/element-partials.md | markdown | 7.9 KB |
| references/example-templates.md | markdown | 14.2 KB |
| references/feeds.md | markdown | 8.4 KB |
| references/headless.md | markdown | 15.4 KB |
| references/image-presets.md | markdown | 14.0 KB |
| references/javascript-boundaries.md | markdown | 12.4 KB |
| references/multi-site-patterns.md | markdown | 13.2 KB |
| references/search.md | markdown | 10.3 KB |
| references/tailwind-conventions.md | markdown | 6.8 KB |
| references/template-caching.md | markdown | 14.2 KB |
| references/third-party-integration.md | markdown | 8.6 KB |
| references/twig-collections.md | markdown | 8.2 KB |
| references/vite-buildchain.md | markdown | 9.3 KB |
references/javascript-boundaries.md
View on GitHub# JavaScript Boundaries Reference
> When to use Twig, Alpine/DataStar, or Vue. Decision tree for interactivity.
## Documentation
- Alpine.js: https://alpinejs.dev/
- DataStar: https://data-star.dev/
- Vue 3: https://vuejs.org/guide/introduction.html
- Pinia: https://pinia.vuejs.org/
- Craft Vite plugin: https://nystudio107.com/docs/vite/
## Common Pitfalls
- Reaching for Vue too early — if Alpine/DataStar can handle it, use that. Vue's bundle size and build complexity aren't justified for a toggle.
- Alpine state sharing — if you're syncing state between multiple Alpine components via `$dispatch` / `window`, you've outgrown Alpine. Move to Vue.
- Inline `<script>` data passing — global variables and inline scripts create implicit dependencies. Use `data-*` attributes.
- Mixing template engines — never put Twig syntax inside `.vue` files or Vue template syntax inside `.twig` files.
- Empty mount points — Craft serves server-rendered HTML. Vue mounts after load. Always render a skeleton in the mount element for SEO and perceived performance.
- Gating SSR-seed rehydration on "no query string / default filters only" — if you server-render a content *seed* for a JS app, a filtered or deep-linked URL then discards it, flashes skeletons, and re-fetches. Always paint the seed first, reconcile in the background. See [SSR-Seed Hydration](#ssr-seed-hydration).
- Nesting Alpine inside Vue or vice versa — they can coexist on the same page but never nested within each other.
## Table of Contents
- [The Decision Tree](#the-decision-tree)
- [Twig Only (Default)](#twig-only-default)
- [Alpine.js / DataStar (UI State)](#alpinejs--datastar-ui-state)
- [Vue 3 (Application State)](#vue-3-application-state)
- [Coexistence Rules](#coexistence-rules)
- [Consent-Gated Embeds](#consent-gated-embeds)
## The Decision Tree
```
Is there client-side state?
├── NO → Twig only (server-rendered, zero JS)
└── YES → Is it UI state or application state?
├── UI STATE (toggles, visibility, simple interactions)
│ → Alpine.js or DataStar
│ Examples: mobile menu, accordion, tabs, dropdown, modal, tooltip
└── APPLICATION STATE (data fetching, filtering, real-time)
→ Vue 3 (+ Pinia for stores)
Examples: search, filtering, paginated lists, dashboards, forms with validation
```
### Definition of Terms
- **UI state:** visibility toggles, open/close, active tab, scroll position. The HTML exists in the DOM (server-rendered by Twig). JS decorates it.
- **Application state:** data loaded from APIs, filtered/sorted/paginated collections, form state across steps. Vue owns the DOM — Twig provides the mount point.
## Twig Only (Default)
The default for everything. No JavaScript unless proven necessary.
```twig
{# Standard component — zero JS, fully server-rendered #}
{%- tag 'article' with { class: classes.implode(' ') } -%}
{%- include '_atoms/images/image--responsive' with {
image: props.get('image'),
preset: 'teaser',
} only -%}
<div class="p-4">
{%- include '_atoms/texts/text--h3' with {
content: props.get('heading'),
} only -%}
</div>
{%- endtag -%}
```
## Alpine.js / DataStar (UI State)
Twig renders the full HTML. Alpine or DataStar adds behavior via attributes.
Both fill the same role — pick one per project, don't mix them.
### Alpine.js
The established choice. Uses `x-*` attributes for directives.
```twig
{# Alpine: mobile navigation #}
<nav x-data="{ open: false }" class="lg:hidden">
{%- include '_atoms/buttons/button--hamburger' with {
label: 'Toggle menu',
} only -%}
<div x-show="open"
x-transition
x-cloak
class="fixed inset-0 z-50 bg-brand-surface">
<button @click="open = false" class="absolute top-4 right-4">
{%- include '_atoms/icons/icon--fa' with {
icon: 'fa-solid fa-xmark',
label: 'Close menu',
} only -%}
</button>
<ul class="flex flex-col gap-4 p-8">
{%- for item in props.get('items') -%}
<li>
{%- include '_atoms/links/link--navigation' with {
text: item.title,
url: item.url,
active: item.active ?? false,
} only -%}
</li>
{%- endfor -%}
</ul>
</div>
</nav>
```
```twig
{# Alpine: accordion #}
<div x-data="{ active: null }">
{%- for item in props.get('items') -%}
<div class="border-b border-brand-muted">
<button @click="active = active === {{ loop.index }} ? null : {{ loop.index }}"
class="w-full text-left py-4 flex justify-between"
:aria-expanded="active === {{ loop.index }}">
{{ item.heading }}
<i class="fa-solid fa-chevron-down transition-transform"
:class="active === {{ loop.index }} && 'rotate-180'"
aria-hidden="true"></i>
</button>
<div x-show="active === {{ loop.index }}"
x-collapse>
<div class="pb-4">
{{ item.content }}
</div>
</div>
</div>
{%- endfor -%}
</div>
```
### DataStar
The modern alternative. Uses HTML-native `data-*` attributes and signals for
reactivity. Lighter weight, SSE-driven updates, no custom directive syntax.
DataStar is the successor to tools like Sprig — it handles server-side
reactivity through SSE without requiring a Craft plugin.
```twig
{# DataStar: mobile navigation #}
<nav data-signals="{ open: false }" class="lg:hidden">
<button data-on-click="$open = !$open">
{%- include '_atoms/icons/icon--fa' with {
icon: 'fa-solid fa-bars',
label: 'Toggle menu',
} only -%}
</button>
<div data-show="$open"
class="fixed inset-0 z-50 bg-brand-surface">
<button data-on-click="$open = false" class="absolute top-4 right-4">
{%- include '_atoms/icons/icon--fa' with {
icon: 'fa-solid fa-xmark',
label: 'Close menu',
} only -%}
</button>
<ul class="flex flex-col gap-4 p-8">
{%- for item in props.get('items') -%}
<li>
{%- include '_atoms/links/link--navigation' with {
text: item.title,
url: item.url,
active: item.active ?? false,
} only -%}
</li>
{%- endfor -%}
</ul>
</div>
</nav>
```
### When Alpine vs DataStar
| Consideration | Alpine.js | DataStar |
|--------------|-----------|----------|
| Syntax | `x-*` custom directives | `data-*` HTML-native attributes |
| Reactivity | Client-side signals | Client-side signals + SSE for server updates |
| Bundle | ~15KB | ~12KB |
| Ecosystem | Mature, large plugin ecosystem | Newer, growing |
| Server updates | Requires separate AJAX/fetch | Built-in via SSE (`data-on-load`) |
Both handle the same use cases: toggles, accordions, tabs, modals, tooltips,
dropdowns, form validation feedback. Pick one per project based on team
familiarity and whether you need SSE-driven server updates.
## Vue 3 (Application State)
Vue owns its DOM subtree. Twig provides mount points and initial data.
### Mount Point Pattern
Twig renders the mount element with initial config as JSON:
```twig
{# In a view or organism #}
<div id="search-app"
data-config="{{ {
endpoint: alias('@searchUrl'),
index: currentSite.handle ~ '_entries',
filters: availableFilters,
}|json_encode|e('html_attr') }}">
{# Skeleton/loading state — replaced by Vue on mount #}
<div class="animate-pulse space-y-4">
<div class="h-48 bg-brand-muted rounded-lg"></div>
<div class="h-4 bg-brand-muted rounded w-3/4"></div>
</div>
</div>
```
### Vue Entry Point
```typescript
import { createApp } from 'vue';
import { createPinia } from 'pinia';
import SearchApp from '../vue/apps/SearchApp.vue';
const element = document.getElementById('search-app');
if (element) {
const config = JSON.parse(element.dataset.config);
const app = createApp(SearchApp, { config });
app.use(createPinia());
app.mount(element);
}
```
### Vite Multi-Entry
Each Vue feature gets its own entry point, loaded only on pages that need it.
See `vite-buildchain.md` for the full Vite setup and conditional loading pattern.
```typescript
// vite.config.ts
export default defineConfig({
build: {
rollupOptions: {
input: {
app: 'src/js/app.ts',
search: 'src/js/apps/search.ts',
},
},
},
});
```
```twig
{# Load Vue app entry only on pages that need it #}
{%- block pageJs -%}
{{ craft.vite.script('src/js/apps/search.ts') }}
{%- endblock -%}
```
### Vue Project Structure
```
src/js/
├── app.ts # Main: Alpine/DataStar setup, global utilities
├── apps/ # Vue mini-app entry points (one per feature)
│ └── search.ts
├── composables/ # Shared Vue composables
├── interfaces/ # TypeScript interfaces
├── stores/ # Pinia stores
├── utils/ # Shared utilities
└── vue/
├── _atoms/ # Vue atomic components (mirror Twig structure)
├── _molecules/
├── _organisms/
└── apps/ # Vue app root components
```
Vue components mirror the Twig atomic structure and use the same Tailwind classes
and brand tokens. They're the client-rendered equivalent of their Twig counterparts.
### Data Handoff Rules: Twig → Vue
- Pass initial data via `data-*` attributes (JSON-encoded).
- Vue reads on mount. After mount, Vue owns all state.
- **Never** embed Twig variables inside Vue template syntax.
- **Never** use inline `<script>` blocks to pass data.
- **Never** let Vue reach outside its mount element to read DOM content.
### SSR-Seed Hydration
When you server-render a *seed* of real content for the app to rehydrate from — to avoid a skeleton flash and the initial API round-trip — the rehydration logic is where it goes wrong:
- **Always paint the seed on the first frame, then reconcile the real state in the background** (stale-while-revalidate). Do **not** gate "use the seed" on "no query string / default filters only" — that makes every filtered or deep-linked URL throw away the server-rendered content, drop back to skeletons, and re-fetch: a visible wipe even on warm-cache loads. Reconcile the filtered state *without* flipping the loading flag back to skeletons.
- Add a `showLoading`-style parameter so **user-initiated** actions (clicking a filter) still get feedback, while the **initial** background reconcile stays silent.
- Watch for artificial delays on loading flags — a hard-coded `setTimeout(() => loading = false, 1000)` adds a full second to every fetch.
**Testing gotcha:** if the store persists filter state to `localStorage` and rewrites the URL on load (`history.pushState`), a "bare URL" test gets hijacked by a returning visitor's persisted filters. Test the clean first-load path in an **isolated browser context** (incognito / fresh profile), not your normal session.
## Coexistence Rules
1. **Alpine/DataStar and Vue can coexist** on the same page. Alpine/DataStar handles site chrome (nav, accordions). Vue handles feature SPAs (search, filtering).
2. **Never nest** Alpine/DataStar inside a Vue-mounted element or vice versa.
3. **Communication** between Alpine/DataStar and Vue: use custom events on `document`.
4. **One Alpine instance per element.** Never nest `x-data` inside another `x-data` (use Alpine stores instead).
5. **Vue mini-apps, not Vue SPAs.** Each feature gets its own entry point and mount point. Never mount Vue on `<body>` or `<main>`.
## Consent-Gated Embeds
```twig
{# Alpine version #}
<div x-data="{ consent: false }"
@consent-granted.window="consent = true">
<template x-if="consent">
{%- include '_atoms/embeds/embed--video' with {
embed: props.get('embed'),
} only -%}
</template>
<template x-if="!consent">
<div class="bg-brand-muted p-8 text-center rounded-lg">
<p>Accept cookies to view this video.</p>
<button @click="$dispatch('open-consent')" class="underline">
Manage cookie preferences
</button>
</div>
</template>
</div>
```
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |