Repository: alpinejs/alpine
Stars: 31453
CLAUDE.md
Alpine.js Development Guidelines
Pull Request Evaluation Criteria
When evaluating pull requests for Alpine.js, assess the following:
1. Tests
- Are tests provided for the change?
- Do existing tests still pass?
- For configuration changes (package.json, build scripts), tests may not be required
2. Code Style
- Does the code match Alpine's existing patterns?
- Check indentation, naming conventions, and structure
- For package.json changes, ensure consistency with other packages in the monorepo
3. Code Quality
- Is the code clean and maintainable?
- Is the change focused and minimal?
- Are there any unnecessary changes or complexity?
- Does this PR contain changes that should apply elsewhere?
4. Simplicity
- Is this a simple, focused change?
- Does it follow Alpine's philosophy of simplicity?
- Could it be implemented more simply?
- Are the proposed additions intuitive for users? or do they require extra knowledge that they have to dig for.
5. Precedent
- Does this PR (both public facing additions and internal implementation) follow established precedents in the project
- Does it use terms that are unfamiliar to the project as of yet?
6. Description Quality
- Is there a clear explanation of what/why/how?
- Are breaking changes documented?
- Is backward compatibility addressed?
7. Community Engagement
- Are there comments, reviews, or discussions?
- Has it been approved by maintainers?
- Are there any conflicting opinions or unresolved concerns?
Mergeability Rating
Based on the above, rate as:
- HIGH: Ready to merge (all criteria met, approved)
- MEDIUM: Needs attention (technically sound but missing reviews/tests)
- LOW: Requires work (has issues or conflicts to resolve)
Project Structure
Alpine.js is a monorepo with packages in /packages/:
- Each package has its own package.json
- Build outputs go to dist/ with .cjs.js, .esm.js, and .min.js versions
- Browser tests use Cypress, unit tests use Vitest
- CI runs on GitHub Actions
Common Commands
Build
npm run build # Build all packagesBrowser tests (Cypress)
npm test # Run all tests
npx cypress run --spec ./tests/cypress/integration/[filename].spec.js # Run single specUnit tests (Vitest)
npx vitest run tests/vitest/[filename].spec.js # Run single specReview PRs
gh pr list # List open PRs
gh pr view [number] # View PR details
gh pr diff [number] # View code changes
gh pr checks [number] # Check CI statusManual Testing
1. Edit ./index.html at project root
2. Open in browser at http://alpine.test/ (assumes local dev server mapped to directory name)
Summary
After assessing the pull request on the above qualities, provide a summary explaining the problem this PR addresses and the fix, and why it's a good or bad fix. Do it in plain language as if you are personally advising me on what the PR is and weather or not I should merge it. And if not, what might need to be addressed first. If things need to be addressed, offer to address them yourself.
Please use code snippets to establish a starting point and and ending point if helpful. For example, when explaining the problem, it is often easier to provide a brief explanation alongside a code snippet of what is currently problematic, then when explaining the solution, showing what new code will allow a fix if applicable.
README.md
Alpine.js
Go to the Alpine docs for most things: Alpine Docs
You are welcome to submit updates to the docs by submitting a PR to this repo. Docs are located in the /packages/docs directory.
Stay here for contribution-related information.
Looking for V2 docs? here they are
<p align="center"><a href="https://alpinejs.dev/patterns"><img src="/hero.jpg" alt="Alpine Component Patterns"></a></p>
Contribution Guide:
Quickstart
* clone this repo locally
* run npm install & npm run build
* Include the /packages/alpinejs/dist/cdn.js file from a <script> tag on a webpage and you're good to go!
Brief Tour
You can get everything installed with:
npm install in the root directory of this repo after cloning it locally.This repo is a "mono-repo" using npm workspaces for managing the packages. Each package has its own folder in the /packages directory.
Rather than having to run separate builds for each package, all package bundles are handled with the same command: npm run build
Here's a brief look at each package in this repo:
Package | Description
--- | ---
alpinejs | The main Alpine repo with all of Alpine's core
collapse | A plugin for expanding and collapsing elements using smooth animations
csp | A repo to provide a "CSP safe" build of Alpine
docs | The Alpine documentation
focus | A plugin that allows you to manage focus inside an element
history | A plugin for binding data to query string parameters using the history API (name is likely to change)
intersect | A plugin for triggering JS expressions based on elements intersecting with the viewport
mask | A plugin for automatically formatting a text input field as a user types
morph | A plugin for morphing HTML (like morphdom) inside the page intelligently
persist | A plugin for persisting Alpine state across page loads
The compiled JS files (as a result of running npm run [build/watch]) to be included as a <script> tag for example are stored in each package's packages/[package]/dist directory.
Each package should at least have: a "cdn" build that is self-initializing and can be included using the src attribute in a <script defer> tag, and a module.[esm/cjs].js file that is used for importing as a JS module (cjs for node, esm for everything else).
The bundling for Alpine V3 is handled exclusively by ESBuild. All of the configuration for these builds is stored in the scripts/build.js file.
Testing
There are 2 different testing tools used in this repo: Cypress (for integration tests), and Vitest (for unit tests).
All tests are stored inside the /tests folder under /tests/cypress and /tests/vitest.
If you wish to only run Cypress and open it's user interface (recommended during development), you can run: npm run cypress
If you wish to only run Vitest tests, you can run npm run vitest like normal and target specific tests.