# 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

```bash
# Build
npm run build                # Build all packages

# Browser tests (Cypress)
npm test                     # Run all tests
npx cypress run --spec ./tests/cypress/integration/[filename].spec.js  # Run single spec

# Unit tests (Vitest)
npx vitest run tests/vitest/[filename].spec.js  # Run single spec

# Review 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 status
```

## Manual 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](https://alpinejs.dev)

You are welcome to submit updates to the docs by submitting a PR to this repo. Docs are located in the [`/packages/docs`](/packages/docs) directory.

Stay here for contribution-related information.

> Looking for V2 docs? [here they are](https://github.com/alpinejs/alpine/tree/v2.8.2)

<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](packages/alpinejs) | The main Alpine repo with all of Alpine's core
[collapse](packages/collapse) | A plugin for expanding and collapsing elements using smooth animations
[csp](packages/csp) | A repo to provide a "CSP safe" build of Alpine
[docs](packages/docs) | The Alpine documentation
[focus](packages/focus) | A plugin that allows you to manage focus inside an element
[history](packages/history) | A plugin for binding data to query string parameters using the history API (name is likely to change)
[intersect](packages/intersect) | A plugin for triggering JS expressions based on elements intersecting with the viewport
[mask](packages/mask) | A plugin for automatically formatting a text input field as a user types
[morph](packages/morph) | A plugin for morphing HTML (like morphdom) inside the page intelligently
[persist](packages/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.