Keeping Alpine.js + Django templates sane in a large app

I built a big app the "boring" way: server-rendered Django templates + Alpine.js for interactivity, no SPA. ~50 Django apps, a lot of screens, one developer. Alpine is the perfect amount of JavaScript for this — until the app gets large and you start hitting its sharp edges.

Here are the patterns that kept it maintainable, and the gotchas that cost me real hours. All of it is stuff I wish someone had told me at line 1.

The mental model: islands, not an app

The trap with Alpine in a big project is treating it like a mini-SPA — global stores everywhere, components reaching into each other. Don't. Treat each interactive region as an island: a self-contained Alpine component hydrating one chunk of server-rendered HTML. The server owns the data and the page; Alpine owns this widget's behaviour.

Two rules fall out of that, and they're the difference between "fine at 10 screens" and "fine at 200."

Rule 1: register components — stop writing logic inline

Inline x-data="{ ... }" is lovely for a toggle. For anything real, it's a liability — and it has a nasty failure mode.

Put a literal double-quote inside an inline expression and you silently close the HTML attribute early:

<!-- ❌ Alpine sees x-data="{ label: "  — the rest becomes broken markup -->
<div x-data="{ label: "Save", open: false }">

The component doesn't throw. It just… doesn't initialize, and depending on where the parser gives up, your expression can dump into the page as visible text. Worse, it often renders fine in your quick manual check but breaks somewhere else — and it's invisible to a lot of smoke tests because it's an HTML-parse issue, not a JS error.

The fix isn't "remember to use single quotes." It's: anything beyond a line or two becomes a registered component.

// static/js/components.js
document.addEventListener('alpine:init', () => {
  Alpine.data('projectBoard', () => ({
    open: false,
    label: 'Save',           // real quotes, real editor, real linting
    toggle() { this.open = !this.open },
  }))
})

<div x-data="projectBoard"> … </div>

Now the logic lives in a .js file your editor and linter understand, the template stays declarative, and the quoting footgun is gone.

Rule 2: never put a "rich" JS instance on reactive state

This one cost me the most time, so I'll be specific. Alpine makes your state reactive by wrapping it in a deep Proxy (via @vue/reactivity). That's great for plain data. It's poison for objects that do their own identity bookkeeping internally — a TipTap/ProseMirror editor, a map instance, a <canvas> controller, a WebSocket.

// ❌ ProseMirror starts throwing "Applying a mismatched transaction"
Alpine.data('editor', () => ({
  editor: null,
  init() { this.editor = new Editor({ element: this.$refs.box }) }, // now a Proxy
}))

The editor stores references to its own nodes/state and compares them by identity. Once Alpine has proxied it, this.editor is not the object the editor thinks it is, and its internal === checks fail in baffling ways.

The fix: keep non-plain instances off reactive state entirely. A closure is cleanest:

// ✅ the editor lives in closure scope — never proxied
Alpine.data('editor', () => {
  let editor
  return {
    init()    { editor = new Editor({ element: this.$refs.box }) },
    bold()    { editor.chain().focus().toggleBold().run() },
    destroy() { editor?.destroy() },
  }
})

If it must live on this, mark it so the reactivity engine skips it (obj.__v_skip = true before assigning, i.e. markRaw). But closure scope is simpler and I reach for it every time. Rule of thumb: only plain, serializable data goes on x-data.

Rule 3: x-data initializers snapshot — use init/x-effect for async

x-data runs once, eagerly, and takes whatever the expression evaluates to right then.

<!-- ❌ `stats` is the Promise fetchStats() returned, not the resolved data -->
<div x-data="{ stats: fetchStats() }">

You'll see [object Promise] or stale/empty state and chase it for an hour. Load then assign:

<div x-data="{ stats: null, async init() { this.stats = await fetchStats() } }">
  <template x-if="stats">…</template>
</div>

Same shape bit me with theme switching: reading a value once at init captures it forever. If something needs to react to a change (a store value, a media query, a fetched result), it belongs in x-effect or an explicit assignment — not in the initializer expression.

Rule 4: pass server data as data, not string interpolation

The tempting thing is to jam Django context straight into an Alpine expression: x-data="{ items: {{ items }} }". It works until a value contains a quote or a newline, and then you're back in Rule 1's parser hell. Use Django's json_script:

{{ items|json_script:"board-data" }}

<div x-data="{ items: JSON.parse(document.getElementById('board-data').textContent) }">

Server renders JSON safely into a <script type="application/json">; Alpine reads it. Clean separation: Django owns the data, the template just carries it, Alpine consumes it.

The small Django-template traps

Two that bit me more than once:

• {# … #} is single-line only. A comment that wraps across lines renders as literal visible text — and if it's sitting next to an Alpine attribute, chaos. Use {% comment %} … {% endcomment %} for anything multi-line.
• Shared islands, single-sourced. The nav bar, the sidebar, the top bar — build each as one island partial you include everywhere, not a per-page fork. The day I stopped copy-pasting the nav component was the day the footer stopped mysteriously drifting between pages.

What "sane" ended up meaning

Nothing exotic — just discipline:

1. Islands, not a SPA. Server owns data + page; Alpine owns a widget.
2. Register non-trivial components in a JS file; inline only for toggles.
3. Plain data only on x-data — rich instances live in closures.
4. Async loads via init/x-effect, never the initializer expression.
5. Server → client via json_script, never string interpolation.
6. A browser smoke run as a release gate, because the worst Alpine bugs are HTML-parse issues that pass unit tests.

Alpine scaled to a genuinely large app for me — but only once I stopped treating it like React-lite and started treating it like sprinkles on server-rendered HTML.

---

I write these while building a free, full-lifecycle PM platform in the open — if the build-in-public stuff is your thing, the rest of the series is here.