{"id":10492,"library":"alpinejs","title":"Alpine.js","description":"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.","status":"active","version":"3.15.11","language":"javascript","source_language":"en","source_url":"https://github.com/alpinejs/alpine","tags":["javascript"],"install":[{"cmd":"npm install alpinejs","lang":"bash","label":"npm"},{"cmd":"yarn add alpinejs","lang":"bash","label":"yarn"},{"cmd":"pnpm add alpinejs","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"const Alpine = require('alpinejs');","symbol":"Alpine","correct":"import Alpine from 'alpinejs';"},{"note":"Plugins are imported from their respective packages and registered with `Alpine.plugin()`.","symbol":"Alpine plugins","correct":"import Focus from '@alpinejs/focus';\nimport Collapse from '@alpinejs/collapse';"},{"note":"For TypeScript users, import the `Alpine` type to extend or type custom magic properties or component data.","symbol":"Alpine types","correct":"import type { Alpine } from 'alpinejs';"}],"quickstart":{"code":"import Alpine from 'alpinejs';\n\n// Register a global data store or component for use with `x-data=\"myStore\"`\nAlpine.data('myCounter', () => ({\n  count: 0,\n  message: 'Hello Alpine!',\n  init() {\n    // Optional initialization logic\n    console.log('myCounter component initialized');\n  },\n  increment() {\n    this.count++;\n  },\n  decrement() {\n    this.count--;\n  }\n}));\n\n// Register a global magic property like $myMagic\nAlpine.magic('myMagic', el => 'This is a magic string!');\n\n// Start Alpine.js\nAlpine.start();\n\n// Typically, Alpine.js is then used in HTML like this:\n/*\n<div x-data=\"myCounter\">\n    <h1 x-text=\"message\"></h1>\n    <p>Count: <span x-text=\"count\"></span></p>\n    <button @click=\"increment\">+</button>\n    <button @click=\"decrement\">-</button>\n    <p x-text=\"$myMagic\"></p>\n</div>\n*/","lang":"typescript","description":"Demonstrates importing Alpine.js, registering a global data component, defining a magic property, and starting Alpine programmatically. Shows how it maps to HTML usage."},"warnings":[{"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.","message":"Alpine.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.","severity":"breaking","affected_versions":">=3.0.0"},{"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.","message":"Content 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.","severity":"gotcha","affected_versions":">=3.0.0"},{"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.","message":"Reactivity 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.","severity":"gotcha","affected_versions":">=3.0.0"},{"fix":"Refactor `x-init=\"doSomething()\"` to `x-init=\"() => doSomething()\"` or, for more complex async setups, `x-init=\"async () => { await fetchData(); this.data = result; }\"`.","message":"While `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.","severity":"deprecated","affected_versions":">=3.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"Alpine.js script was not loaded or imported before it was accessed, or `Alpine.start()` was not called.","error":"ReferenceError: Alpine is not defined"},{"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()`.","cause":"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.","error":"Alpine Expression Error: Cannot read properties of undefined (reading 'foo')"},{"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`.","cause":"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.","error":"Content Security Policy: The page’s settings blocked the loading of a resource at self (\"script-src\")."}],"ecosystem":"npm"}