GO — Healthy across the board

• Last commit today
• 24+ active contributors
• Distributed ownership (top contributor 49% of recent commits)
• MIT licensed
• CI configured
• Tests present

_{Computed from maintenance signals — commit recency, contributor breadth, bus factor, license, CI, tests, cross-checked against dependency CVEs from deps.dev and OpenSSF Scorecard}

Alpine.js is a rugged, minimal JavaScript framework that lets you compose interactive behavior directly in HTML markup using declarative directives like x-data, x-bind, and x-for—without a build step or heavy virtual DOM. It solves the problem of adding interactivity to server-rendered HTML without the complexity of React, Vue, or Svelte, targeting developers who want just enough JavaScript to enhance templates. Monorepo using npm workspaces with /packages directory containing: alpinejs (core engine in packages/alpinejs/src with directives subdir), 9+ plugins (collapse, csp, focus, history, intersect, mask, morph, persist), and docs (packages/docs). Core lives in packages/alpinejs/src/alpine.js (main entry) with directive implementations in packages/alpinejs/src/directives/*.js. Builds use ESBuild (scripts/build.js) to produce cdn.js and module.[esm/cjs].js per package.

Web developers and designers building server-rendered applications (Rails, Laravel, Django) who need lightweight interactivity in their HTML—particularly those allergic to JavaScript bundling, large frameworks, or the complexity of component state management. Contributors are framework enthusiasts who value minimal dependencies and progressive enhancement.

Production-ready and actively maintained. Alpine.js has accumulated significant real-world usage (evidenced by the monorepo structure with 10+ official plugins), comprehensive test coverage via Cypress and Vitest, GitHub Actions CI/CD via release.yml and run-tests.yml, and a mature plugin ecosystem in /packages. The codebase shows disciplined organization with minimal dependencies (esbuild for bundling, no heavy runtime deps).

Low risk for a mature framework. The monorepo uses npm workspaces which adds some complexity to dependency management, but the primary core (alpinejs package) has minimal external deps. Main risks: single-framework-author-dependent (check commit history for maintainer concentration), the CSP package (packages/csp) suggests security constraints in certain deployment environments that require specialized builds. Breaking changes between V2→V3 were significant (hence the V2.8.2 branch still maintained), so major version upgrades require care.

The repo actively supports V3 with ongoing plugin development and documentation. The monorepo structure suggests focus on plugin ecosystem expansion. GitHub Actions workflows (release.yml, run-tests.yml) indicate regular automated releases and test runs. The /packages/docs directory is actively maintained for documentation updates per the README.

git clone https://github.com/alpinejs/alpine.git
cd alpine
npm install
npm run build
# Output is in packages/alpinejs/dist/cdn.js

Then include the dist file in a script tag on an HTML page, or import as a module.

Daily commands: Development: npm run build to compile once, or npm run watch for continuous rebuild. Testing: npm test (Cypress headless), npm run cypress (Cypress UI), npm run vitest (unit tests). The built artifacts in packages/alpinejs/dist/cdn.js can be immediately used in any HTML file via <script src="..."></script>.

• packages/alpinejs/src/alpine.js — Main entry point that orchestrates framework initialization, directive registration, and core lifecycle.
• packages/alpinejs/src/reactivity.js — Core reactivity engine implementing observable state tracking and dependency graph management.
• packages/alpinejs/src/directives/index.js — Central registry and loader for all Alpine directives (x-data, x-bind, x-if, etc.).
• packages/alpinejs/src/scope.js — Manages component scopes, context binding, and variable resolution for template expressions.
• packages/alpinejs/src/evaluator.js — Expression parser and evaluator that safely executes JavaScript snippets within Alpine contexts.
• packages/alpinejs/src/magics/index.js — Magic property registry ($el, $refs, $dispatch, $watch) providing framework utilities to templates.
• packages/alpinejs/src/mutation.js — DOM mutation observer that detects new Alpine components and triggers initialization.

• Reactivity Engine (JavaScript Proxy, WeakMap) — Wraps component state in a Proxy to track dependencies and notify listeners of mutations.
  • Failure mode: Property mutations not detected; components become stale
• Directive Processor (DOM API, regex parsing) — Parses directive syntax (x-bind, x-if, x-for) and executes corresponding DOM updates.
  • Failure mode: Directives fail to bind; invalid syntax silently ignored or throws
• Evaluator (new Function, Scope proxying) — Safely executes JavaScript expressions from markup within the component scope.
  • Failure mode: Syntax errors in templates; scope variable leakage or access violations
• Mutation Observer (MutationObserver API) — Detects added/removed DOM nodes and initializes or tears down Alpine components accordingly.
  • Failure mode: Dynamic components not initialized; manual init required
• Scheduler (requestAnimationFrame, microtasks) — Batches reactive updates and flushes changes to DOM in the next animation frame.
  • Failure mode: Multiple updates cause redundant re-renders or thrashing

• Browser DOM → Alpine.init() — MutationObserver detects x-data elements and passes them to framework initialization
• Alpine.init() → Reactivity Engine — Component scope object is wrapped in a Proxy to enable transparent state tracking
• Reactivity Engine → Directive Processors — When reactive state changes, subscribers (directives) are notified and re-evaluated
• Directive Processors → Browser DOM — Directives update element attributes, classes, content, or structure based on state
• Browser Events → Evaluator — x-on handlers and computed expressions are evaluated when user interactions occur

Add a new directive

1. Create a new file in packages/alpinejs/src/directives/ named x-yourname.js (packages/alpinejs/src/directives/x-yourname.js)
2. Export an object with setup(element, { expression, modifiers, original }) method (packages/alpinejs/src/directives/x-yourname.js)
3. Register directive in packages/alpinejs/src/directives/index.js by adding to exported object (packages/alpinejs/src/directives/index.js)
4. Run npm run build to bundle and test with a sample HTML file (packages/alpinejs/builds/cdn.js)

Add a new magic property

1. Create a new file in packages/alpinejs/src/magics/ named $yourname.js (packages/alpinejs/src/magics/$yourname.js)
2. Export a function that receives scope and returns the magic value (packages/alpinejs/src/magics/$yourname.js)
3. Register in packages/alpinejs/src/magics/index.js magics object (packages/alpinejs/src/magics/index.js)
4. Build with npm run build and verify magic is accessible via $yourname in templates (packages/alpinejs/builds/cdn.js)

Create a new Alpine plugin package

1. Create new directory packages/yourplugin with src/, builds/, and package.json (packages/collapse/package.json)
2. Implement plugin export in packages/yourplugin/src/index.js using Alpine.plugin() API (packages/collapse/src/index.js)
3. Build distribution files to packages/yourplugin/builds/cdn.js and module.js (packages/collapse/builds/cdn.js)
4. Run npm run build from root to compile all packages in workspace (package.json)

• JavaScript Proxies — Enable transparent reactivity by intercepting property access without explicit getters/setters
• MutationObserver — Detect dynamically added x-data elements and initialize them without manual triggers
• Function Evaluation (new Function) — Allow developers to write plain JavaScript expressions in HTML attributes without build step
• npm Workspaces — Manage core and plugin packages with unified build pipeline and shared dependencies

• Runtime expression evaluation vs compile-time templates

  • Why: Enables zero-build-step setup and maximum flexibility in markup
  • Consequence: Slightly larger bundle size and potential XSS surface if user input is not sanitized

• DOM-centric instead of VDOM

  • Why: Minimize framework overhead and work naturally with server-rendered HTML
  • Consequence: Morphing complex trees requires directive-specific logic; cannot batch updates across components

• Minimal directive API surface

  • Why: Keep learning curve flat and encourage semantic markup patterns
  • Consequence: Some advanced patterns (slots, scoped slots) require workarounds or plugins

• Does not provide server-side rendering or framework-level SSR tooling
• Does not include a routing library (separate package)
• Does not implement CSS-in-JS or component scoped styles
• Does not enforce TypeScript or provide type definitions for template expressions

• Avg cyclomatic complexity: ~6 — Core files (evaluator, reactivity, directive processing) are moderately complex due to Proxy interception, expression parsing, and DOM manipulation; most utility functions are simple.
• Largest file: packages/alpinejs/src/directives/x-for.js (280 lines)
• Estimated quality issues: ~4 — Unsafe eval patterns, lack of TypeScript, minimal input validation in expression parser, and synchronous DOM operations create surface for bugs.

• Unsafe expression evaluation (Medium) — packages/alpinejs/src/evaluator.js: Uses new Function() to execute arbitrary JavaScript from markup, creating XSS risk if user input is interpolated without sanitization.
• Synchronous DOM traversal on mutation (Medium) — packages/alpinejs/src/mutation.js: Walks entire DOM tree for each mutation event; can cause performance degradation with frequent insertions.
• Global state pollution via Alpine.store (Low) — packages/alpinejs/src/store.js: Shared global store object can cause unintended cross-component coupling and difficult-to-trace bugs.

• packages/alpinejs/src/utils/walk.js (Algorithm Complexity) — DOM tree traversal to find directives is O(n) per component; repeated walks during initialization can slow large pages.
• packages/alpinejs/src/reactivity.js (Memory & CPU) — Proxy-based tracking logs all property accesses during expression evaluation, which can create overhead for deeply nested objects.
• packages/alpinejs/src/directives/x-for.js (Rendering) — Keyed list diffing relies on manual key binding; missing keys cause full re-render of all list items.

The monorepo uses npm workspaces which means npm install in root installs all packages; you cannot install individual packages in isolation without extra flags. ESBuild config is centralized in scripts/build.js, not per-package—modification requires understanding the entire build pipeline. The /packages/csp directory produces a separate CSP-compliant build; if your code requires CSP headers, you must use the CSP build, not the standard cdn.js. Documentation lives in /packages/docs which is a separate package build target (likely Astro or similar based on typical Alpine setup), not inline markdown. No obvious .env.example file, so check if any build scripts need environment variables before starting.

• Reactive Proxies — Alpine uses JavaScript Proxies (inferred from x-data behavior) to intercept property access and trigger reactivity without a virtual DOM; understanding this is key to debugging state changes in Alpine.
• Directive-based templating — Alpine's entire API is built on declarative HTML directives (x-data, x-bind, x-for); this pattern is central to how Alpine differs from imperative jQuery or component-based frameworks.
• DOM morphing — The morphing plugin (/packages/morph) intelligently updates HTML while preserving focus and form state, a unique capability when server-pushing HTML updates without full page reloads.
• Content Security Policy (CSP) safe builds — The /packages/csp directory exists because Alpine's default uses inline script evaluation; understanding CSP-safe alternatives is critical for deploying Alpine in security-conscious environments.
• Monorepo workspaces — Alpine's plugin ecosystem is managed via npm workspaces in a single repo; contributors must understand workspace linking to test plugins against core changes.
• ESBuild bundling — All Alpine and plugin builds are orchestrated by scripts/build.js using ESBuild; modifying builds or adding packages requires understanding ESBuild's configuration and entry points.
• Progressive enhancement — Alpine is designed to layer interactivity on server-rendered HTML without breaking when JS fails; this philosophy underpins architectural decisions like avoiding heavy runtime dependencies.

• vuejs/vue — Vue.js is the closest spiritual sibling with similar directive-based templating (v-bind, v-for), but Vue is heavier and includes a full build toolchain; Alpine is Vue's minimal inverse.
• htmx/htmx — HTMX also enables HTML-centric interactivity without heavy JavaScript, but targets server-side HTML swapping; Alpine complements HTMX by handling client-side state and reactivity.
• marko-js/marko — Marko is a similar directive-based template language, but renders server-side; Alpine is its client-side reactive counterpart for enhancing server-rendered HTML.
• alpinejs/alpine-next — Experimental or future Alpine releases and proposals may live here; check if forward-compatibility work is tracked separately.
• tailwindlabs/tailwindcss — Commonly paired with Alpine in tutorials and real projects—TailwindCSS handles styling while Alpine handles interactivity, forming a lightweight modern stack.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for x-modelable directive

The x-modelable directive (packages/alpinejs/src/directives/x-modelable.js) appears to lack dedicated test coverage in the test suite. This two-way binding feature is critical for component composition and deserves thorough unit tests covering edge cases like nested models, reactive updates, and interaction with x-model.

• [ ] Review packages/alpinejs/src/directives/x-modelable.js to understand implementation
• [ ] Check existing test patterns in cypress.json and test structure
• [ ] Create comprehensive tests for: basic two-way binding, nested model updates, interactions with x-model, and cleanup on element removal
• [ ] Ensure tests cover both CDN and module build scenarios

Add GitHub Actions workflow for performance benchmarking

The repo contains a benchmarks/ directory with multiple HTML files (giant.html, loop.html, memory.html, etc.) but no automated CI workflow to track performance regressions across PRs. This is critical for a minimal framework where performance is a key selling point.

• [ ] Review benchmarks/ directory structure and existing benchmark HTML files
• [ ] Create .github/workflows/benchmark.yml that runs benchmarks on each PR using Lighthouse or similar
• [ ] Configure the workflow to compare results against the main branch and comment on PRs with performance delta
• [ ] Document benchmark results in a comment template for PR authors

Add integration tests for x-teleport with nested x-data contexts

The x-teleport directive (packages/alpinejs/src/directives/x-teleport.js) enables moving DOM elements while preserving Alpine reactivity, but lacks test coverage for complex scenarios involving nested x-data scopes, event propagation, and reactivity across teleported boundaries.

• [ ] Study packages/alpinejs/src/directives/x-teleport.js implementation and scope/lifecycle handling
• [ ] Add Cypress tests covering: teleporting elements with nested x-data, reactive updates across teleport boundaries, event listener cleanup, and re-mounting scenarios
• [ ] Test interaction with x-on event handlers on teleported elements
• [ ] Verify memory cleanup when teleported elements are removed

• Add unit tests for packages/alpinejs/src/clone.js (appears to have no corresponding test file in /tests/vitest, yet cloning is core to reactivity). Create /tests/vitest/clone.test.js covering edge cases like circular references and nested objects.
• Expand documentation for x-id directive (packages/alpinejs/src/directives/x-id.js exists but few examples in most Alpine tutorials). Add a new guide to /packages/docs explaining unique ID generation use cases with code samples.
• Create a new plugin scaffold generator script: add scripts/create-plugin.js to automate boilerplate (package.json, src/index.js, builds/) for new contributors, reducing friction for plugin ecosystem growth.

• High · Potential XSS vulnerability in x-html directive — packages/alpinejs/src/directives/x-html.js. The x-html directive allows binding raw HTML content to DOM elements. If user input is passed without sanitization, this could enable Cross-Site Scripting (XSS) attacks. The file packages/alpinejs/src/directives/x-html.js likely implements innerHTML assignment which is a known XSS vector. Fix: Implement strict input validation and sanitization for x-html. Consider using a DOM purification library (e.g., DOMPurify) or restricting x-html to trusted content only. Document security implications clearly in the API.
• Medium · Evaluator function execution without sandboxing — packages/alpinejs/src/evaluator.js, packages/alpinejs/src/scope.js. The evaluator.js file likely executes arbitrary JavaScript expressions from Alpine directives (e.g., x-init, x-bind). If directives contain user-supplied content, this could enable code injection attacks. The scope.js and lifecycle.js may also be vulnerable if they execute user-provided callbacks without restrictions. Fix: Implement a sandboxed execution environment or use a Content Security Policy (CSP) to restrict script execution. Add clear documentation warning against binding untrusted data. Consider implementing a safe expression parser instead of eval-like execution.
• Medium · Outdated axios dependency with known vulnerabilities — package.json. The package.json specifies axios ^0.21.1, which is outdated and contains known security vulnerabilities (CVE-2021-3749 and others). Any code using axios for HTTP requests may be exposed to request forgery or data leakage attacks. Fix: Upgrade axios to version ^1.6.0 or latest stable version (^1.x.x). Run 'npm audit' and 'npm audit fix' to address all reported vulnerabilities in the dependency tree.
• Medium · cypress dependency with potential vulnerabilities — package.json. The package.json specifies cypress ^7.0.0, which is an older version (from 2021). This version may contain known security vulnerabilities and should be updated to current versions. Fix: Upgrade Cypress to the latest stable version (^13.x.x or higher). Run 'npm audit' to identify and address any security issues in the test dependency chain.
• Medium · No explicit Content Security Policy documentation — README.md, .github/SECURITY.md. Alpine.js manipulates the DOM extensively through directives (x-bind, x-html, x-if, etc.). Without proper CSP headers, Alpine applications may be vulnerable to XSS attacks, especially if user input is dynamically bound to the DOM. Fix: Document recommended CSP headers for Alpine.js applications. Provide security guidelines for developers using Alpine, emphasizing the importance of input sanitization and CSP adoption. Include examples of secure patterns.
• Low · Missing security headers in benchmark and demo files — benchmarks/giant.html, benchmarks/init.html, benchmarks/loop.html, index.html, index2.html, morph.html. Benchmark and demo HTML files (benchmarks/giant.html, index.html, index2.html, morph.html) may not include security headers like X-Content-Type-Options, X-Frame-Options, or Strict-Transport-Security, increasing the risk of clickjacking and MIME-type sniffing attacks. Fix: Add security headers to all HTML files used for development and benchmarking. If these are served via a web server, configure appropriate security headers at the server level (nginx, Apache, etc.).
• Low · Potential DOM clobbering in x-ref and x-data directives — packages/alpinejs/src/directives/x-ref.js, packages/alpinejs/src/directives/x-data.js. The x-ref and x-data directives store references in the component scope. If user input is used as property names, DOM clobbering attacks could bypass security checks or interfere with Alpine's internal functionality. Fix: Implement validation to prevent prototype pollution and DOM clobbering. Use Object.create(null) for scope objects where appropriate, and sanitize property names used in x-ref and x-data bindings.
• undefined · undefined — undefined. undefined Fix: undefined

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/alpinejs/alpine shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live alpinejs/alpine repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/alpinejs/alpine.

What it runs against: a local clone of alpinejs/alpine — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in alpinejs/alpine | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 30 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of alpinejs/alpine. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/alpinejs/alpine.git
#   cd alpine
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of alpinejs/alpine and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "alpinejs/alpine(\\.git)?\\b" \\
  && ok "origin remote is alpinejs/alpine" \\
  || miss "origin remote is not alpinejs/alpine (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "packages/alpinejs/src/alpine.js" \\
  && ok "packages/alpinejs/src/alpine.js" \\
  || miss "missing critical file: packages/alpinejs/src/alpine.js"
test -f "packages/alpinejs/src/reactivity.js" \\
  && ok "packages/alpinejs/src/reactivity.js" \\
  || miss "missing critical file: packages/alpinejs/src/reactivity.js"
test -f "packages/alpinejs/src/directives/index.js" \\
  && ok "packages/alpinejs/src/directives/index.js" \\
  || miss "missing critical file: packages/alpinejs/src/directives/index.js"
test -f "packages/alpinejs/src/scope.js" \\
  && ok "packages/alpinejs/src/scope.js" \\
  || miss "missing critical file: packages/alpinejs/src/scope.js"
test -f "packages/alpinejs/src/evaluator.js" \\
  && ok "packages/alpinejs/src/evaluator.js" \\
  || miss "missing critical file: packages/alpinejs/src/evaluator.js"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 30 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~0d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/alpinejs/alpine"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.