alpinejs

library3.15.11jsnpmunverified

Alpine.js is a lightweight, declarative JavaScript framework designed for adding interactive behavior directly into HTML markup, often described as 'Tailwind for JavaScript'. It operates by directly attaching JavaScript behavior to DOM elements via `x-` attributes, avoiding the need for a build step, virtual DOM, or component compilation for many use cases. The current stable version is 3.15.11, with frequent patch and minor releases focusing on bug fixes, performance enhancements, and new directive modifiers. Key differentiators include its minimal bundle size, direct-in-HTML approach, and Vue-like reactivity for small, interactive components, making it ideal for augmenting server-rendered applications or for projects where a full-fledged SPA framework is overkill.

web-framework

npm install alpinejs

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · ALPINEJS

alpinejs

web-frameworkjavascriptv3.15.11

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Alpine

✓ import Alpine from 'alpinejs';

✗ const Alpine = require('alpinejs');

The primary import for Alpine.js. While often used via CDN, module bundlers use this ESM import. CommonJS require is generally discouraged for modern Alpine development.

Alpine plugins

✓ import Focus from '@alpinejs/focus'; import Collapse from '@alpinejs/collapse';

Plugins are imported from their respective packages and registered with `Alpine.plugin()`.

Alpine types

✓ import type { Alpine } from 'alpinejs';

For TypeScript users, import the `Alpine` type to extend or type custom magic properties or component data.

Demonstrates importing Alpine.js, registering a global data component, defining a magic property, and starting Alpine programmatically. Shows how it maps to HTML usage.

import Alpine from 'alpinejs'; // Register a global data store or component for use with `x-data="myStore"` Alpine.data('myCounter', () => ({ count: 0, message: 'Hello Alpine!', init() { // Optional initialization logic console.log('myCounter component initialized'); }, increment() { this.count++; }, decrement() { this.count--; } })); // Register a global magic property like $myMagic Alpine.magic('myMagic', el => 'This is a magic string!'); // Start Alpine.js Alpine.start(); // Typically, Alpine.js is then used in HTML like this: /* <div x-data="myCounter"> <h1 x-text="message"></h1> <p>Count: <span x-text="count"></span></p> <button @click="increment">+</button> <button @click="decrement">-</button> <p x-text="$myMagic"></p> </div> */

Debug

Known issues

breakingAlpine.js v3 introduced significant breaking changes from v2, including changes to the global API (`Alpine.data` vs. `x-data` directly), removal of implicit global state, and changes to magic property definitions. Directives like `x-ref` also behave slightly differently.

fix

Consult the official migration guide from v2 to v3 for a comprehensive list of changes and updated syntax. Many global functions became `x-data` properties or magic properties.

affects: >=3.0.0

gotchaContent Security Policy (CSP) configurations can block Alpine.js's dynamic expression evaluation if not properly configured. Alpine uses `eval` internally, which might conflict with strict `script-src` policies, potentially leading to errors like 'unsafe-eval' blocked.

fix

Ensure your CSP includes `'unsafe-eval'` in the `script-src` directive if dynamic expression evaluation is necessary. Alternatively, for stricter CSPs, consider using a CSP-compatible build or leveraging libraries like `alpine-csp` for pre-compiling expressions, though this may require a build step.

affects: >=3.0.0

gotchaReactivity with `x-model` and other directives can sometimes lead to unexpected timing issues, especially when dealing with form submissions or external state mutations. For instance, `x-model.blur` might not have flushed its value before a form's submit handler runs.

fix

Use modifiers like `.defer` on `x-model` to control when updates propagate. For form submissions, explicitly ensure values are up-to-date or use `Alpine.nextTick()` for post-render logic. Recent versions (v3.15.8) include fixes for `x-model.blur` flushing.

affects: >=3.0.0

deprecatedWhile `x-init` can still execute statements directly, the recommended pattern for `x-init` in Alpine v3+ is to return a function. This returned function will then be executed after the element is added to the DOM and all child components are initialized, which is crucial for handling asynchronous operations correctly.

fix

Refactor `x-init="doSomething()"` to `x-init="() => doSomething()"` or, for more complex async setups, `x-init="async () => { await fetchData(); this.data = result; }"`.

affects: >=3.0.0

Errors

Common errors & fixes

ReferenceError: Alpine is not defined

Alpine.js script was not loaded or imported before it was accessed, or `Alpine.start()` was not called.

fix

Ensure the Alpine.js script tag is present in your HTML (preferably with `defer`) or that `import Alpine from 'alpinejs'; Alpine.start();` is executed in your JavaScript bundle.

Alpine Expression Error: Cannot read properties of undefined (reading 'foo')

Attempting to access a property `foo` within an Alpine expression (e.g., `x-text="foo"`) where `foo` is not defined in the current component's `x-data` scope or a parent scope.

fix

Verify that the property `foo` is declared within the `x-data` object of the current element or one of its ancestors. If it's intended to be global, ensure it's registered with `Alpine.data()` or `Alpine.store()`.

Content Security Policy: The page’s settings blocked the loading of a resource at self ("script-src").

Your browser's Content Security Policy is preventing Alpine.js from executing dynamic JavaScript, typically due to the lack of `'unsafe-eval'` in the `script-src` directive.

fix

Modify your server's CSP header or HTML meta tag to include `'unsafe-eval'` in `script-src`, e.g., `<meta http-equiv="Content-Security-Policy" content="script-src 'self' 'unsafe-eval';">`. Exercise caution with `unsafe-eval`.

Upgrade

Version history

3.15.11latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

21 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/alpinejs/alpine ↗

packagehttps://www.npmjs.com/package/alpinejs ↗

homepagehttps://alpinejs.dev ↗