README

A minimal, modern, multilingual Laravel installation wizard.
shadcn-style UI · light / dark / system theme · 10 languages · zero CDN runtime deps.

When a fresh Laravel app has not yet been installed, laravel-install-wizard gently redirects every route to a clean web-based installer. The user names the app, configures the environment and database, sees PHP requirement and folder permission checks, then clicks Install. A .installed lock file is written and the wizard never appears again.

Highlights
Screenshots
Requirements
Installation
Quick start
Configuration
Multilingual support
Theming
Customizing views and assets
Resetting installation
Security
Testing
Contributing
Versioning
Credits
License

Highlights

Multi-step wizard — Welcome → Environment → Database → Requirements → Permissions → Install
Dynamic branding — enter NativeCode and the installer becomes the NativeCode Installer everywhere
Live database test — MySQL, PostgreSQL, SQLite, SQL Server, validated before continuing
Safe .env writer — preserves comments, leaves unrelated keys alone, validates key format
10 languages out of the box — English, Spanish, French, German, Portuguese, Italian, Japanese, Chinese, Arabic (RTL), Hindi
Light / Dark / System theme — localStorage persistence, OS-preference reactive, no FOUC
shadcn-style UI — HSL CSS variables, Outfit font, accessible menus, keyboard nav
Zero CDN runtime deps — all CSS, JS and confetti inlined; only Google Fonts for Outfit
Production-ready — works without JavaScript via progressive enhancement
Auto-discovered — drop in via Composer, no service-provider wiring required

Screenshots

Add screenshots here once the package is hosted. Suggested shots: docs/welcome-light.png, docs/database-dark.png, docs/complete-rtl.png.

[ welcome — light ]   [ database — dark ]   [ complete — confetti ]

Requirements

PHP 8.1, 8.2, 8.3 or 8.4
Laravel 10, 11 or 12

Installation

composer require nativecodein/laravel-install-wizard

The service provider is auto-registered. On first request, since storage/.installed doesn't exist yet, every route redirects to /install.

Publishing files (optional)

# everything
php artisan vendor:publish --tag=installwizard

# or individually
php artisan vendor:publish --tag=installwizard-config
php artisan vendor:publish --tag=installwizard-views
php artisan vendor:publish --tag=installwizard-lang
php artisan vendor:publish --tag=installwizard-assets

Quick start

Install via Composer.
Open any route in your Laravel app — you'll be redirected to /install.
Enter your application name (e.g. NativeCode).
Fill in environment, database, watch the requirement and permission checks pass.
Click Install NativeCode. The package writes .env, generates APP_KEY, clears caches, creates storage/.installed.
Confetti fires. You're sent back to the route you originally requested.
Future visits never see the wizard again.

Configuration

After publishing the config, all behavior lives in config/installwizard.php:

Key	Default	Description
`installed_file`	`storage_path('.installed')`	Lock file that gates the wizard
`route_prefix`	`install`	URL prefix for wizard routes
`auto_apply_middleware`	`true`	Append the gating middleware to the `web` group automatically
`redirect_after_install`	`/`	Fallback target after install if no intended URL
`required_extensions`	12 standard exts	PHP extensions checked in step 4
`writable_paths`	storage + bootstrap/cache	Paths verified in step 5
`final.run_migrations`	`false`	Run `migrate --force` at the end
`final.run_seeders`	`false`	Run `db:seed --force` at the end
`final.generate_key`	`true`	Generate `APP_KEY` if missing
`final.clear_caches`	`true`	Clear config/route/view/cache stores
`locales`	10 locales	Languages offered in the switcher
`rtl_locales`	`['ar','he','fa','ur']`	Forced right-to-left layout
`default_theme`	`system`	Initial theme: `light`, `dark`, or `system`

Multilingual support

Ten locales ship out of the box. A globe button in the header opens a language picker; the choice persists in the user's session.

Code	Language	Code	Language
`en`	English	`it`	Italiano
`es`	Español	`ja`	日本語
`fr`	Français	`zh`	中文
`de`	Deutsch	`ar`	العربية (RTL)
`pt`	Português	`hi`	हिन्दी

Adding a language

php artisan vendor:publish --tag=installwizard-lang

Create lang/vendor/installwizard/{locale}/messages.php, copy keys from en/messages.php, translate, then declare it in config:

// config/installwizard.php
'locales' => [
    'en' => 'English',
    'tr' => 'Türkçe', // new
],
'rtl_locales' => ['ar', 'he', 'fa', 'ur'], // add new RTL locales here

RTL locales render with dir="rtl" automatically.

Theming

The theme toggle in the header offers three modes:

Light — <html> has no dark class
Dark — <html class="dark">
System — follows prefers-color-scheme and reacts live to OS changes

The choice is stored in localStorage under installwizard.theme. An inline <script> in <head> applies the class before paint, so there is no flash.

Customizing colors

Publish the views, then edit the CSS variables at the top of resources/views/vendor/installwizard/layout.blade.php:

:root {
    --primary: 240 5.9% 10%;
    --background: 0 0% 100%;
    /* … */
}
.dark {
    --primary: 0 0% 98%;
    /* … */
}

All variables follow shadcn/ui conventions — HSL component triplets consumed with hsl(var(--token)).

Customizing views and assets

php artisan vendor:publish --tag=installwizard-views

Views land in resources/views/vendor/installwizard/ and override the package versions automatically. Edit them however you like — the package will pick up your changes immediately.

Assets are inlined into the layout by default, so publishing CSS/JS is only needed if you want to bundle the wizard into your own Vite pipeline.

Resetting installation

# wipe the lock file — wizard appears on the next request
rm storage/.installed

Or programmatically:

app(\Nativecodein\LaravelInstallWizard\Services\Installer::class)->removeLockFile();

Security

The EnvWriter validates env keys against /^[A-Z_][A-Z0-9_]*$/ and rejects anything else.
Existing comments and unrelated .env values are preserved during writes.
All forms are CSRF-protected through the web middleware group.
The locale switcher validates against the configured allow-list before persisting.
The gating middleware only stores intended URLs for GET requests (never AJAX/XHR), preventing redirect loops.
API requests get a 503 JSON response instead of a redirect, preventing fetch/axios redirect loops.
No external CDN dependencies at runtime — all CSS, JS and confetti are inlined.

If you discover a security vulnerability, please email security@nativecode.in rather than opening a public issue.

Testing

composer install
vendor/bin/phpunit

The suite uses Orchestra Testbench and covers:

redirects when not installed / access granted when installed
creation of the .installed lock file
safe .env writing (comment & key preservation)
database tester (success & failure paths)
requirement checker (extensions, writable paths)
middleware redirect-loop avoidance
locale persistence, RTL detection, per-locale translation rendering

Contributing

Contributions are welcome. To get started:

git clone https://github.com/nativecodein/laravel-install-wizard.git
cd laravel-install-wizard
composer install
vendor/bin/phpunit

Submitting changes

Fork the repo and create a feature branch: git checkout -b feature/your-thing
Write or update tests for your change.
Ensure vendor/bin/phpunit passes locally.
Open a pull request describing the why (motivation) and the what (change summary).

Reporting issues

When opening a bug report, please include:

Laravel and PHP versions (php artisan --version, php -v)
The contents of config/installwizard.php if you've customized it
Browser and OS for UI bugs
A minimal reproduction repo if possible

Translations

To contribute a new language, copy src/resources/lang/en/messages.php, translate, and submit a PR. Native speakers reviewing existing translations are also very welcome.

Code style

This project follows PSR-12. Keep controllers thin, services pure, and Blade views accessible. Avoid introducing runtime CDN dependencies — everything that ships in the layout is inlined deliberately.

Versioning

This package follows Semantic Versioning. Breaking changes only ship in major releases.

Credits

NativeCode — original author and maintainer
Laravel — the framework this package extends
shadcn/ui — design tokens and component vocabulary that inspired the UI
Outfit — typeface
All contributors

License

The MIT License (MIT). Please see the LICENSE file for more information.

Contributed by NativeCode
https://nativecode.in

nativecodein / laravel-install-wizard

Maintainers

Package info

Statistics

Security

README

Table of contents

Highlights

Screenshots

Requirements

Installation

Publishing files (optional)

Quick start

Configuration

Multilingual support

Adding a language

Theming

Customizing colors

Customizing views and assets

Resetting installation

Security

Testing

Contributing

Submitting changes

Reporting issues

Translations

Code style

Versioning

Credits

License