CLAUDE.md

1# Project Overview
2 
3Livewire is a full-stack framework for Laravel. It allows you to build dynamic front-end applications without leaving the comfort of PHP/Laravel/Blade.
4 
5It is similar to projects like Phoenix Liveview however it isn't "live" in that it doesn't use real-time connections like websockets. Just simple http requests.
6 
7It renders on the server and uses morphing algorithm to path the DOM with updates from the server.
8 
9It "dehydrates" the state of a component into a JS-consumable object that is passed back to the server to be "hydrated" during the next request.
10 
11# Tech Stack
12 
13- Laravel + PHP + Vanilla JS
14- JS Bundling: esbuild
15 
16# Project Structure
17 
18```
19src/           → The PHP source files
20- Features/    → Individual ~modules to isolate features
21js/            → The JavaScript source files
22tests/         → A smattering of PHP tests however, most tests are inside their src/Feature directories
23```
24 
25# Development Workflow
26 
27## Setup
28 
29Run `composer setup` to install all dependencies (PHP, JS, ChromeDriver).
30 
31## Build JS assets
32 
33Run `npm run build` to bundle the JS
34 
35**IMPORTANT:** Do not commit `dist/` files. They are built in CI.
36 
37# Code Patterns
38 
39- Write JavaScript without semicolons
40- Always use `let` (no `const`)
41- Strive for single-word features and affordances (ex. `wire:click.stop` instead of `wire:click.stop-propagation`)
42 
43# Testing
44 
45Most browser and unit tests live inside of feature directories for example:
46 
47src/Features/SupportSlots/[UnitTest.php|BrowserTest.php]
48 
49```bash
50composer test                                        # all tests
51composer test:unit                                   # unit tests only
52composer test:browser                                # browser tests (headless)
53composer test:browser:headed                         # browser tests (opens Chrome)
54composer test:browser -- --filter="SupportCSP"       # specific browser tests
55```
56 
57**IMPORTANT:** Never run the full Livewire browser test suite — it takes too long. Always use `--filter` to run only the specific tests relevant to your changes. The full suite runs in CI.
58 
59# Releasing
60 
61## Bumping Alpine (optional)
62 
63If you need to update the Alpine.js dependency before a release:
64 
65```bash
66npm run bump-alpine
67```
68 
69Then commit the updated `package.json` and `package-lock.json`.
70 
71## Creating a release
72 
731. Go to **Actions → "Release" → "Run workflow"**
742. Enter the version number (e.g. `4.3.0` — the `v` prefix is added automatically)
753. The workflow installs deps, builds assets, runs JS tests, creates a tag with the built `dist/` files, and creates a GitHub Release with auto-generated notes
76