Guide · Open source

How to use Alpine.js: install, build and add interactivity

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

Alpine.js is a lightweight JavaScript framework for adding interactive behavior to web pages by writing small pieces of logic directly in your HTML markup. This guide explains how to get the repository building locally, where the compiled script lives, and where to find the full usage documentation. After reading it, you will know how to build Alpine from source and include it on a page with a script tag.

Alpine.jsalpinejs/alpine · ★ 32k · MIT Install options & downloads

Quick start

1Check prerequisites. Install Node.js and npm on your machine.
2Clone the repository. Run git clone https://github.com/alpinejs/alpine to get a local copy.
3Install dependencies. Run npm install in the root directory of the cloned repo.
4Build the packages. Run npm run build to produce the compiled files for every package.
5Include the script. Add a script defer tag pointing to /packages/alpinejs/dist/cdn.js on your page.
6Read the docs. Open alpinejs.dev for usage details on directives and features, since the README covers mainly contribution topics.

What Alpine.js is and who it suits

Alpine.js is aimed at developers adding dropdowns, tabs or toggles to server-rendered pages. It also suits teams that want light interactivity without a full single-page app build setup.

The repository README is mainly a contribution guide. Most usage details live on the official docs at alpinejs.dev, so treat this repository as the place to build from source and contribute.

Good fit: server-rendered pages that need small interactive pieces
Good fit: contributors who want to change the core library or plugins
Not a fit: projects that need a full app framework with routing and a build pipeline

Prerequisites: Node.js and npm

The install method described in the README is clone-and-build. You need Node.js and npm installed on your machine before you start.

Install Alpine.js by cloning and building the repository

Clone the repository, install its dependencies from the root directory, then build the packages. The same build command handles every package in the monorepo.

git clone https://github.com/alpinejs/alpine
npm install
npm run build

Include Alpine on a web page with a script tag

After building, include the compiled file /packages/alpinejs/dist/cdn.js from a script tag on your page. The README describes this file as the self-initializing build, which can be loaded with the src attribute in a script defer tag.

Each package stores its compiled files in its own dist directory, so the core file is found under packages/alpinejs.

Build output for each package is in packages/[package]/dist
The bundling for Alpine V3 is handled by ESBuild; its configuration is in scripts/build.js

<script defer src="/packages/alpinejs/dist/cdn.js"></script>

Understand the optional plugins

The monorepo contains the core library plus optional plugins. Each plugin lives in its own folder under /packages. The README lists these plugins with a short description of each.

collapse: expanding and collapsing elements with smooth animations
focus: managing focus inside an element
intersect: triggering expressions when an element enters the viewport
mask: automatically formatting a text input as the user types
morph: morphing HTML inside the page
persist: persisting Alpine state across page loads
history: binding data to query string parameters (the README notes the name may change)
csp: a CSP-safe build of Alpine

Run the tests when contributing

The repository uses Cypress for integration tests and Vitest for unit tests. All tests are stored under /tests, in /tests/cypress and /tests/vitest.

Open the Cypress interface during development: npm run cypress
Run Vitest tests: npm run vitest

npm run cypress
npm run vitest

What people use it for

Adding a dropdown menu to a server-rendered page without a build pipeline
Building tabs or show/hide toggles on an existing site
Using the collapse plugin to animate expanding and collapsing sections
Contributing a fix or a new feature to the core library or a plugin

Frequently asked questions

Is Alpine.js free to use?

The repository is licensed under MIT. The README states the licence, and you can use it under those terms; check the LICENSE file in the repo for the full text.

What do I need to install Alpine.js?

The README lists Node.js and npm as prerequisites. You clone the repository, run npm install, then npm run build.

Where is the Alpine.js documentation?

Most usage details are on the official site at alpinejs.dev. The docs source is in the /packages/docs directory of this repo, and the README points readers there for most topics.

Which file do I include on my page?

Include /packages/alpinejs/dist/cdn.js from a script tag after running the build. The README says this is all you need to start working.

What is the difference between Alpine.js and htmx?

Alpine.js adds small pieces of logic directly in markup, while htmx is commonly compared with it as another option for light interactivity. The README lists htmx, Petite Vue and Stimulus as comparable projects, but does not compare them in detail, so review each project's docs before choosing.

Where can I find the Alpine V2 docs?

The README links to the V2 documentation at a tagged version of the repository. For current usage, use the V3 docs at alpinejs.dev.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Alpine.js suits developers who want to add dropdowns, tabs and toggles to server-rendered pages with a single script tag and no build pipeline. Teams that need routing or a full app framework should choose a different tool, and anyone who wants usage guidance should rely on alpinejs.dev because this README focuses on contributing.

Install options & downloads