Skip to content

getting-started.md

Latest commit

 

History

History
191 lines (142 loc) · 5.96 KB

getting-started.md

File metadata and controls

191 lines (142 loc) · 5.96 KB
Raw
title Getting started
description Install the modular Alpine toolkit and register feature plugins.

Requirements

  • Alpine.js v3+
  • A bundler with ESM support (Vite, Webpack, etc.) or native ES modules

Install essentials

Start with the core primitives and the five essential modules:

pnpm add alpinejs \
  @ailuracode/alpine-core \
  @ailuracode/alpine-ui \
  @ailuracode/alpine-theme \
  @ailuracode/alpine-toggle \
  @ailuracode/alpine-media \
  @ailuracode/alpine-scroll \
  @ailuracode/alpine-sidebar \
  @ailuracode/alpine-toast

Add more packages later — each one is an independent npm dependency.

Direct registration (recommended for most apps)

Every feature plugin is a plain Alpine callback. Register them in your app entry, then start Alpine:

import Alpine from "alpinejs";
import { themePlugin } from "@ailuracode/alpine-theme";
import { mediaPlugin } from "@ailuracode/alpine-media";
import { scrollPlugin } from "@ailuracode/alpine-scroll";

Alpine.plugin(themePlugin());
Alpine.plugin(mediaPlugin());
Alpine.plugin(scrollPlugin());

Alpine.start();

@ailuracode/alpine-core ships the registration guards so a second plugin that asks for $store.theme throws RegistrationError instead of silently overwriting the host's store.

Code splitting (dynamic import())

If your bundler splits dynamic imports into separate chunks, register heavy plugins through a thin wrapper that resolves the chunk lazily:

import Alpine from "alpinejs";

const plugins = [
  () => import("@ailuracode/alpine-theme").then((m) => m.themePlugin()),
  () => import("@ailuracode/alpine-media").then((m) => m.mediaPlugin()),
  () => import("@ailuracode/alpine-toast").then((m) => m.toastPlugin()),
];

await Promise.all(plugins.map((load) => load().then((p) => Alpine.plugin(p))));

Alpine.start();

This gives you code-splitting without a dedicated registry abstraction — the feature plugins themselves stay Alpine callbacks, which keeps them discoverable and easy to test.

Direct HTML usage

Stores

<button @click="$store.theme.set('dark')">Dark</button>
<button @click="$store.theme.set('light')">Light</button>
<button @click="$store.theme.set('system')">System</button>
<button @click="$store.theme.toggle()">Toggle</button>

<div x-show="$store.media.matches('mobile')">Mobile layout</div>

<button x-show="$store.scroll.showToTop" @click="$store.scroll.toTop()">
  Back to top
</button>

Magics

<button @click="$toast('Changes saved', { variant: 'success' })">Notify</button>

Push a plain payload from server-rendered data or events:

<div
  x-data
  x-init="$toast.fromPayload({ title: 'Saved', variant: 'success' })"
></div>

Package tiers

Tier Packages When to add
Essentials theme, media, scroll, sidebar Most Alpine apps
Headless UI dialog, menu, tooltip, toast, tabs, accordion, command, carousel Accessible UI you style yourself
Extended network, attention, clipboard, platform, toggle Connectivity, clipboard, device hints
Advanced geo, battery, export, share, attention, notify, calendar, json-api Specialized browser APIs
Query query + adapter + devtools Client-side data cache (see Query)

CDN

<script type="module">
  import Alpine from "https://esm.sh/alpinejs";
  import { themePlugin } from "https://esm.sh/@ailuracode/alpine-theme";

  Alpine.plugin(themePlugin());
  Alpine.start();
</script>

To react to theme transitions from a CDN snippet:

<script type="module">
  import Alpine from "https://esm.sh/alpinejs";
  import { themePlugin } from "https://esm.sh/@ailuracode/alpine-theme";

  Alpine.plugin(themePlugin());
  Alpine.start();

  // Apply classes via the $theme magic once Alpine is ready
  document.addEventListener("alpine:init", () => {
    Alpine.store("theme").on("change", (detail) => {
      document.documentElement.classList.toggle("dark", detail.resolved === "dark");
    });
  });
</script>

TypeScript

Each package ships dist/index.d.ts (imports) and dist/global.d.ts (Alpine augmentations):

/// <reference types="@types/alpinejs" />
/// <reference types="@ailuracode/alpine-core" />
/// <reference types="@ailuracode/alpine-theme" />
/// <reference types="@ailuracode/alpine-toast" />

Or import the plugin module — generated types augment globals automatically.

Avoiding name collisions

Alpine silently overwrites whatever a previous plugin registered under the same key. Toolkit feature plugins guard their registrations through @ailuracode/alpine-core and throw RegistrationError("REGISTRATION_COLLISION") instead of clobbering the host's store or magic.

If the host already owns a name (own $store.theme, sibling toolkit plugin registered $store.toast, etc.) the recommended fix is renaming the integration surface, not overriding:

Alpine.plugin(themePlugin({ storeKey: "appearance" })); // → $store.appearance
Alpine.plugin(toastPlugin({ magicKey: "notify" }));     // → $notify

Feature plugin options accept storeKey / magicKey (and the matching one for directives) for exactly this case. The escape hatch is the { override: true } option on guardStore / guardMagic / guardDirective, but prefer renaming — silent overwrites are the bug class this guard exists to catch.

See Core — Avoiding name collisions for the full API and the architecture:check rule that enforces it.

Next steps