jonpurvis/squeaky
Squeaky is a Laravel package that scans your Blade templates and CSS to find unused classes, helping you trim dead styles and keep front-end assets lean. Simple to install and run, it makes cleaning up your app's CSS a quick, repeatable part of your workflow.
Version context: v3.3.0 is a major release (the changelog compares against v2.4.0, so treat everything between as a v3 breaking wave). Two constraints now define who can install it:
Minimum path to first value:
composer require jonpurvis/squeaky --dev (it is test/tooling-adjacent, so keep it out of production dependencies unless you have a runtime use case).php artisan vendor:publish --tag="squeaky-config" — verify the exact tag in the README for v3) and commit it. The config file is the primary surface area; read it top-to-bottom before running anything, because defaults are what most teams silently inherit.tests/Pest.php (or via the plugin/extension registration the README specifies for Pest 5) so its expectations are available in your suite.main, and compare the output. The delta between those two runs is your real backlog.Where to look first: the README's v3 section, then CHANGELOG.md (the GitHub release note is a one-liner and does not enumerate the v2→v3 breaking changes), then the published config file. Do not trust the release note alone for upgrade scope.
First real use case: wire it into a single existing test file or CI job rather than the whole suite, so you learn its output format and failure modes before it gates anyone's PR.
CI as the primary integration point. The package's value compounds when it runs unattended. Add a dedicated job (or extend your existing Pest job) that runs after the test suite, not before — you want failures to be attributable. Keep it in its own job initially so a failing check is visually distinct from a red test run.
Local pre-push hook. Because Pest 5 is a moving target and the checks are fast, add the invocation to a Composer script (composer check) and reference that from Husky/simple-git-hooks. Developers then run the same command CI runs, which kills the "works locally" class of complaint.
Config as code, not as defaults. Treat the published config like phpunit.xml: reviewed in PRs, commented when a value is deliberately loosened. When you suppress or exclude something, add a one-line reason. This is the single highest-leverage habit with quiet, configurable quality tools — the diff history becomes your audit trail.
Baseline-then-ratchet. On adoption, don't fix everything at once. Capture the current state, commit it as an accepted baseline (or scoped ignore list), and then tighten incrementally in follow-up PRs. This is the pattern that gets a quality gate adopted rather than reverted.
Pair it with architecture tests. Pest 5's architecture testing does the structural work; keep this package's concerns in a separate, clearly-labelled test file (e.g. tests/Feature/Quality/) with a @group or distinct directory so it can be run or skipped independently. Mixing them makes failures ambiguous.
Scope it per-PR where practical. For monorepos or multi-domain apps, run it against the changed paths in PR workflows and against the full tree on a nightly job. Full-tree runs on every push get slow and noisy fast.
Version pinning discipline. Given the v2→v3 jump, pin to ^3.3 rather than ^3.0 while the v3 line settles, and read each minor's diff before bumping. A major release with a one-line changelog is a signal that the diff, not the prose, is the documentation.
The changelog is the weakest link here. v3.3.0's notes list a single PR, yet the version leaps from v2.4.0 — meaning v3.0.0 through v3.2.x changes are not described. Before upgrading, read the actual compare diff and the CHANGELOG.md, not the release note. Budget real time for this; it is the main risk in this release.
Laravel 10/11 removal is a hard stop, not a warning. Composer will resolve you backwards to v2.x if you're on Laravel 11, which can look like "the new version doesn't work" when it's really constraint resolution. Use composer why-not jonpurvis/squeaky 3.3.0 to get the blocking constraint named explicitly instead of guessing.
Pest 5 is a suite-wide upgrade, not a package upgrade. Adopting this version may force you to move Pest and every Pest plugin/extension you rely on in the same PR. Do that migration as its own PR with no other changes, otherwise a red build tells you nothing about which dependency caused it. Watch for third-party Pest plugins that haven't tagged Pest 5 support yet — that, not Squeaky, is usually the real blocker.
PHP version floors move with Pest. Pest 5's PHP requirement will be higher than what many Laravel 11 apps run. Check composer.json require.php in the package and match it against your CI matrix before writing any code — a failing matrix entry on PHP 8.3 when the package needs newer is a wasted afternoon.
Config caching bites in CI. If your pipeline runs php artisan config:cache, remember published package config is baked in at cache time. Run php artisan config:clear (or re-cache after publishing) when a config change appears to have no effect. This is the number-one false "the package is broken" report.
Parallel testing interacts badly with per-process state. If the package writes temp files, caches, or a baseline artifact, --parallel can produce flaky, order-dependent failures. Verify against a parallel run early; if it's unstable, isolate the check into the non-parallel job rather than debugging intermittently.
Debugging failures: run with -v / the package's verbose flag first, then narrow to a single test file. If the output is truncated, check whether the package truncates large result sets via config — the "missing" results are often just below the display threshold.
Extension points: the config file and the package's published/overridable classes are the stable seams. Prefer configuration and small wrapper tests over subclassing internals — with a major version this recent and a thin changelog, internal class names are the least stable thing in the codebase to build on.
Upgrade sequencing recommendation: (1) upgrade Pest and plugins, (2) upgrade to Laravel 12 if you haven't, (3) then bump Squeaky from v2 to ^3.3, (4) re-publish and diff the config file, (5) run the full suite plus a full-tree check and review the new output before enabling it as a gate.
How can I help you explore Laravel packages today?