Jump Start Laravel Package

Getting Started

Jump Start is an opinionated Laravel starter kit — a scaffold consumed once at project creation rather than a runtime dependency. "Day-to-day" usage means living inside the toolchain it installs (Pest, Pint, Rector, PHPStan, Tailwind/Blade formatting), not calling its API.

Prerequisites for v2.0.0

• PHP 8.4 (hard floor — ^8.4 in composer.json; 8.3 will refuse to install)
• Composer 2.x
• Node + npm (now mandatory for composer test, not just for asset builds)

First run

1. Create the project from the kit (Composer create-project or the repo template, per its README).
2. cp .env.example .env && php artisan key:generate
3. composer install
4. npm ci — required before composer test in v2, because Pint's Blade formatter shells out to Prettier.
5. php artisan migrate
6. composer test to prove all four gates pass on an untouched skeleton.

Where to look first

• composer.json → the scripts block (test, plus whatever lint / analyse / refactor targets exist)
• pint.json → preset and the Pint/laravel_blade rule
• phpstan.neon.dist → level and paths (now includes tests/)
• rector.php → rule sets and paths
• .github/workflows/* → the four-gate CI job, SHA-pinned actions, Composer + npm caches

First real use case: run the gates on the fresh skeleton to confirm the local toolchain matches CI, then make the skeleton's own diff the baseline for every subsequent commit.

Implementation Patterns

Scaffold once, own it forever. There is no composer update path from v1 to v2. Treat the generated project as your code; upgrading means diffing your tree against a fresh v2.0.0 checkout and porting config/workflow changes by hand.

Keep an upstream git remote pointed at the kit repository. Cherry-pick tooling improvements (CI hardening, Rector sets) as isolated commits instead of hand-merging later.

Fast local loop, slow full gate. Reserve composer test (all four gates) for pre-push and CI. During development:

vendor/bin/pest --filter=CheckoutTest
vendor/bin/pest --parallel
vendor/bin/pint --dirty
vendor/bin/phpstan analyse --memory-limit=1G
vendor/bin/rector --dry-run

pint --dirty is essential now — a full Blade format pass across the repo is slow and produces noisy diffs.

Commit hygiene / pre-commit hook running pint --dirty plus a filtered Pest run keeps the formatting-only commits separate from behavioural ones. Mixing them makes Rector/Pint churn unreviewable.

CI ordering for fail-fast: format check → static analysis → Rector dry-run → tests. Formatting failures are cheapest to surface and cheapest to fix.

Rector belongs on a branch, not in the hot path. With tests/ now on Rector's paths, a rule-set bump can rewrite large parts of your test suite. Run it deliberately, review as its own PR, never as part of composer test in a blocking pre-commit hook.

Ratcheting a new project into all four gates. Because v2.0.0 analyses tests/ with PHPStan, generate phpstan-baseline.neon immediately after scaffolding and commit it. That locks in current noise and makes level bumps incremental.

Adopt Tailwind class sorting on day one. Retrofitting prettier-plugin-tailwindcss into an existing Blade-heavy app produces one enormous diff. On a new Jump Start app it's free — let it be the default from the first commit.

Mirror CI in Docker/Composer scripts so npm ci is part of any "test" target. The classic failure is a green local run and a red CI run because the local node_modules predates the lockfile.

Gotchas and Tips

PHP 8.4 is a hard lockout. Docker php:8.4-cli/php:8.4-fpm, Sail base image, Herd/Valet PHP selector, and any shared CI runner must be on 8.4. A stale 8.3 image fails at composer install with a confusing platform error — check php -v in the failing container first.

Pest 5 / PHPUnit 13 is a major jump. Expect breakage in: phpunit.xml schema, tests/Pest.php plugin registration, expectation API edge cases, and anything touching --parallel or coverage. Third-party Pest plugins (pest-plugin-*, arch presets) must have Pest 5 support — pin them.

composer test now has a Node dependency. Pint's Blade formatter invokes Prettier. If npm ci hasn't run, formatting either fails or silently skips Blade files. Add it to bootstrap docs, Docker entrypoints, and the CI step list before the PHP gates.

Prettier plugin resolution is config-driven. prettier-plugin-blade and prettier-plugin-tailwindcss must be listed in a Prettier config file (.prettierrc, prettier.config.js, or whatever Pint's Bladetool rule reads) — installed-but-unreferenced plugins often do nothing. Symptom: pint reports success but Blade classes stay unsorted.

Blade formatting will fight your merge conflicts. Any long-lived branch touching .blade.php files will conflict against a format pass. Rebase before running pint, not after. Also check pint.json exclusions so vendor/published-package Blade views aren't churned.

PHPStan on tests/ is noisier than on app/. Expect larastan-adjacent extension needs, higher memory limits, and errors about dynamic test helpers. Baseline them rather than lowering the global level.

npm update vs npm ci. The advisory fixes (vite, postcss, nanoid, shell-quote) only land if the refreshed package-lock.json is committed. Running npm update locally and forgetting the lockfile means CI restores the vulnerable tree and the advisories reappear. Conversely, if the lockfile changes, npm ci in CI will hard-fail on any mismatch with package.json.

SHA-pinned GitHub Actions cut both ways. Great for supply-chain safety, but no automatic security patches and no version-drift visibility. Add a Dependabot/Renovate github-actions rule, or you'll be manually auditing commits every quarter.

Cache keys must cover both ecosystems. Composer cache on composer.lock, npm cache on package-lock.json — a shared or under-specified key silently serves stale vendor/ or node_modules/ across PHP/Node version bumps.

Extension points worth knowing: pint.json (preset, rules, exclude, and the Blade/Tailwind rules), phpstan.neon.dist (paths, level, baseline), rector.php (rule sets, skip lists), tests/Pest.php for the Pest 5 analysis plugins, and .github/workflows/ for the four gates. Everything is plain config in your own repo — no vendor lock-in, which is the main reason to pick this kit over hand-assembling the same stack.