AlpineComponentLoader is a dependency-free browser runtime for turning reusable HTML templates into Alpine-powered Custom Elements. Version 1.0.0 expands that core idea into a complete component workflow with a demand-loaded runtime, project scaffolding, manifests, route shards, Vite integration, static Node SSR, progressive hydration, and development tooling.

The simple path still stays simple: add Alpine.js and a CDN import map, define a component, and use it as a normal HTML element. As a project grows, the same runtime can add typed props, data loading, persistence, error boundaries, offline policies, testing fixtures, accessibility checks, and generated contracts without forcing an application rewrite.

Key Features

  • Build-free, demand-loaded runtime: Native ES modules run directly from jsDelivr, while optional capabilities are fetched only when configuration, markup, or an API call activates them.
  • Flexible component model: Load remote or inline templates, render in Shadow or Light DOM, declare typed attributes, use slots, styles, external assets, Alpine stores, and component helpers.
  • Data and state management: Built-in requests support cancellation, retries, polling, response parsing, cache strategies, persistent storage adapters, migrations, and state-preserving reloads.
  • Lifecycle and resilience: Lazy and idle loading, dynamic components, transitions, keep-alive behavior, nearest error boundaries, fallback UI, cleanup hooks, and form-associated components are included.
  • SSR and progressive hydration: The Node entry can render components with initial data, then hydrate them immediately or on visibility, interaction, idle time, or a media query.
  • Integrated project tooling: The CLI can create projects, serve with targeted template HMR, generate manifests and TypeScript declarations, build route shards and offline assets, watch source directories, and run accessibility audits.
  • Production-minded extras: Vite delivery, Trusted Types and CSP support, recursive sanitization, adaptive prefetch, structured observability, debugger and accessibility tools, plus Playwright and Vitest helpers are available as opt-in entries.

Quick Start

The recommended browser setup uses an import map. Pinning the CDN URL to v1.0.0 keeps the deployed module graph reproducible:

HTML 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
<script defer src="https://cdn.jsdelivr.net/npm/alpinejs@3.15.12/dist/cdn.min.js"></script>
<script type="importmap">
    {
        "imports": {
            "alpine-component-loader": "https://cdn.jsdelivr.net/gh/LTDev-LLC/alpine-component-loader@v1.0.0/dist/index.min.js"
        }
    }
</script>

<script type="module">
    import AlpineComponentLoader from 'alpine-component-loader';

    AlpineComponentLoader.config({ basePath: '/components/' });
    AlpineComponentLoader.define('profile-card', 'profile-card.html', {
        shadow: true,
        attributes: {
            name: { type: String, required: true }
        }
    });
    await AlpineComponentLoader.start();
</script>

<profile-card name="Ada">
    <button slot="action">Follow</button>
</profile-card>

For projects that need the CLI, Node SSR, or package-manager integration, install directly from GitHub:

BASH 
1
2
3
npm install github:LTDev-LLC/alpine-component-loader alpinejs
npx alpine-component-loader create my-app
npx alpine-component-loader serve

The browser runtime supports Alpine.js 3.14 through 3.x. The CLI, build tools, testing integrations, and Node-only SSR entry require Node.js 22 or newer.

Why This Project Matters

There is a wide gap between copying HTML fragments by hand and adopting a full client-side framework with a mandatory build pipeline. AlpineComponentLoader fills that gap. It starts as a small, build-free component loader, but it has a path to the features larger applications eventually need: explicit contracts, route-aware delivery, server rendering, hydration, diagnostics, security controls, and repeatable tooling.

That makes it useful both for progressively enhancing a traditional site and for building a modular Alpine.js application without turning the browser runtime into a monolithic bundle.

Stack

  • ES2022 modules and Custom Elements for the demand-loaded browser runtime
  • Alpine.js 3.14-3.x for component reactivity
  • Node.js 22+ for the CLI, static SSR, development server, and project tooling
  • Vite integration for applications that want a conventional development and production workflow
  • Playwright and Vitest helpers for browser and component testing

If you want reusable Alpine.js components that can begin with a script tag and grow into an SSR- and tooling-aware application architecture, AlpineComponentLoader provides the bridge.