Migration from Alpine v2 to v3

Learn the key changes when upgrading to Alpine 3.

Upgrading to Alpine 3

Alpine 3 was a major rewrite that reduced the core size by 85% while improving performance and simplifying the API. Most of the concepts from v2 remain, but there are a few breaking changes you need to know.

Key Changes

• $el now refers to the root element of the component (the element with x-data), not the element where the expression is evaluated. Use $refs for child elements.
• x-spread has been replaced by x-bind with an object argument or by Alpine.bind().
• Alpine.data() must be called before Alpine.start(). Use the alpine:init event to register your data factories.
• Custom directives and magics are now registered using Alpine.directive() and Alpine.magic() instead of Alpine.directive() and Alpine.magic() (same names, slightly different signatures).
• The init method inside x-data is now the recommended way to run setup code, replacing the old x-init inline functions.
• Alpine no longer depends on @popperjs/core internally; anchor positioning is now a separate plugin.

Quick Migration Steps

• Update the CDN link or npm package to v3.
• Replace x-spread with x-bind or Alpine.bind().
• Move Alpine.data() calls before Alpine.start().
• Adjust any custom directives or magics to the new API.
• Test all components, especially those relying on $el.

Resources

The Official Upgrade Guide provides a comprehensive, step‑by‑step migration path. Most v2 markup works with minimal changes.