Installer Laravel Package

Getting Started

The installer is a global dev-machine tool, not a project dependency — it should never appear in an application's composer.json.

composer global require laravel/installer

# verify the binary is reachable
laravel --version
laravel new --help      # read this before scripting anything

The most common first-day failure is a PATH problem: ~/.composer/vendor/bin, ~/.config/composer/vendor/bin (Linux/macOS) or %APPDATA%\Composer\vendor\bin (Windows) must be on PATH. If laravel is "not found" but composer global show laravel/installer works, it is PATH, not the package.

First real use case — replace the two-step composer create-project + manual setup with one command:

laravel new acme-portal
# interactive: starter kit (none / React / Vue / Livewire / Svelte),
# testing framework (Pest / PHPUnit), database, git init, package manager, Boost, teams

Where to look first:

• laravel new --help — the authoritative flag list for the version you have installed.
• Creating a Laravel project — the only official docs; the repo README is intentionally thin.
• The changelog — this is where behaviour actually gets documented (--no-node, --no-boost, laravel package, Svelte kits, Bun support, JSON output for agents).

Implementation Patterns

1. One command, one convention, shared by the whole team. The highest-value pattern is agreeing on an invocation and putting it in your onboarding doc so every new repo looks identical:

laravel new my-app --react --pest --database=pgsql --git --no-interaction

Confirm exact flag names with --help first — this package moves fast, and flags have been added and renamed across 5.x (--no-node, --no-boost, --pm variants, Svelte support, teams support).

2. Non-interactive scaffolding for scripts and CI-ish flows. --no-interaction skips every prompt, which is what you want for smoke tests, template repos, and devcontainer provisioning. Combine it with explicit flags so nothing depends on prompt defaults that shift between releases:

laravel new "$APP" \
  --no-interaction --no-node --no-boost \
  --database=sqlite --pest --git

Note the deliberate --no-node: on CI you usually install and build assets in a separate, cacheable job rather than inside the scaffold step.

3. Skip Node when the frontend is built elsewhere. --no-node exists precisely for teams running npm/pnpm/yarn/Bun in their own pipeline, or backend-only repos where npm install && npm run build is pure latency. Pair it with --no-boost when you also don't want the AI-tooling install step.

4. Choose the package manager explicitly. The installer detects/uses npm, pnpm, yarn, or Bun (with bunx as the npx equivalent), and passes the right flags to each. If your team standardises on pnpm or Bun, say so in the scaffold command rather than letting detection guess — a repo scaffolded with npm and then converted to pnpm is a classic source of lockfile churn on day one.

5. Package scaffolding via laravel package. For internal packages, laravel package (added in 5.31) removes the copy-paste-a-skeleton ritual. Treat the generated structure as a starting point, add your org's composer.json metadata, CI workflow, and Pint/PHPStan config immediately — the scaffolder's opinions are generic.

6. Machine-readable output. Since 5.27 the installer can emit structured JSON when invoked by AI agents/tooling. If you are automating scaffolds inside an agent or a wrapper script, prefer that over scraping ANSI output; the human-facing output has already changed several times (task-based concise output, Prompts callouts, gradient banner).

7. Wrap it in a one-liner for repeatability. A tiny shell function or Make target keeps flags out of muscle memory:

newapp() { laravel new "$1" --react --pest --database=pgsql --no-interaction && cd "$1" && composer run dev; }

8. Prefer composer create-project as the documented fallback. For locked-down machines without a global Composer bin, or pinned-version reproducibility, composer create-project laravel/laravel still works — you just lose starter-kit wiring, database/git automation, and post-install hooks.

Gotchas and Tips

• Version drift silently changes scaffolds. Two developers on different installer versions get different starter-kit wiring, different Boost constraints, different default prompts. Pin expectations in your onboarding docs and composer global update laravel/installer deliberately, not incidentally.
• Self-update loops. There have been multiple fixes for update loops, especially on Windows (PRs #510, #500). If laravel keeps re-updating or hangs at startup, run laravel self-update once explicitly and check whether your global Composer bin is writable — permission failures are a common root cause.
• Prompt defaults are not API. Defaults have flipped (e.g. teams defaulting to "no"). Anything scripted should pass flags explicitly instead of accepting whatever the current default is.
• TTY handling in automation. Interactive child processes (npm install, boost:install, hooks) only attach a real TTY when appropriate; earlier versions ignored --no-interaction here. If a CI run hangs on a prompt, it is usually a subprocess, not laravel new itself — pass --no-interaction and the --no-node / --no-boost escapes.
• Order of operations matters for Boost. boost:install was moved after Node package installation; if you reorder hooks in a custom workflow, you can break the frontend tooling that Boost expects.
• Windows specifics. There is a long tail of Windows-only fixes: php artisan dev support, queue:listen --timeout=0, stdin attach on native Windows, quoting version constraints so ^ survives cmd.exe. On Windows, always quote Composer constraints in any wrapper script you write.
• Existing directories and absolute paths. Passing an absolute path or a directory that already exists has historically had edge cases on Linux/Unix. Scaffold into a fresh directory, or let the installer create it — don't scaffold into a non-empty directory you care about.
• Herd/Valet detection drives the "your app is ready" output. It reads stored paths; a stale Herd/Valet installation can produce a wrong local URL. The URL shown is informational — verify with php artisan serve if it looks off.
• .env mutation is regex-based. APP_URL is rewritten by regex (PR #487); if you pre-seed a custom .env or use an unusual key format, re-check the file after scaffolding rather than assuming it was left alone.
• Git and DB are performed for you. --git initialises a repo and the installer touches database config; if you are scaffolding into an existing repository or a monorepo subfolder, decide explicitly whether you want that behaviour before running it, and clean up partial directories if a step fails mid-way (a failed npm install leaves a valid PHP app with no built assets — not a broken repo, just an incomplete one).
• Security posture: the installer has had fixes around not executing postinstall scripts from installed packages, and around Composer github-oauth credential handling in CI. Keep it current if you run it in any shared/automated environment.
• Extension point, if you need one: --using / custom installer scripting lets you point at a fork or custom scaffold; for org-wide templates a small wrapper script is usually simpler than forking the installer. The installer's own logic is small and readable — when behaviour surprises you, read the command class rather than the changelog.
• It will not manage your app afterwards. No upgrade path, no migrations, no dependency updates — once laravel new finishes, the project is a normal Laravel app and the installer is out of the picture.