FilamentLaravel/README.md

FilamentLaravel

A Laravel 12 application scaffolded with Jetstream and Livewire, built with Vite and Tailwind CSS. This repo includes common local‑dev conveniences (concurrent processes for PHP server, queue worker, logs, and Vite) and a modern testing setup using Pest.

If you’re new to this codebase, this README helps you get it running locally and understand where things live.

Note: The project name in .env is APP_NAME=FilamentApp. The repository name is FilamentLaravel.

Stack

• Language: PHP ^8.2
• Framework: Laravel ^12.0
  • Jetstream ^5.3
  • Sanctum ^4.0
  • Livewire ^3.x and Livewire Flux ^2.x
• Frontend tooling: Vite ^6, Tailwind CSS ^4, PostCSS
• Package managers: Composer (PHP), npm (Node)
• Testing: Pest ^3 (with PHPUnit under the hood)

Requirements

• PHP 8.2+
• Composer 2.x
• Node.js 18+ and npm 9+
• A database (MySQL/MariaDB). Defaults from .env:
  • DB_HOST=127.0.0.1, DB_PORT=3306, DB_DATABASE=filamentlaravel, DB_USERNAME=root, DB_PASSWORD=ServBay.dev
• Optional services depending on features you use:
  • Redis (default client configured: phpredis)
  • Mail catcher or SMTP server (defaults to MAIL_MAILER=log)

Quick start

1. Clone and install dependencies

   git clone <your-fork-or-repo-url>
   cd FilamentLaravel
   composer install
   npm install
   

2. Configure environment

   cp .env.example .env   # if .env doesn’t exist
   php artisan key:generate
   

   • Update .env database credentials as needed.
   • Ensure SESSION_DRIVER=database (already set) and run migrations (next step) to create the sessions table.

3. Create database and run migrations

   php artisan migrate
   

4. Run the app (all-in-one dev experience)

   composer run dev
   

   This starts:

   • php artisan serve (Laravel app)
   • php artisan queue:listen --tries=1 (queue worker)
   • php artisan pail --timeout=0 (pretty app logs)
   • npm run dev (Vite)

   Or run them individually:

   php artisan serve
   npm run dev
   

5. Visit the app at the URL shown by php artisan serve (defaults to http://127.0.0.1:8000). You can also set APP_URL in .env.

Scripts

• Composer
  • composer run dev — concurrently run server, queue worker, logs, and Vite
• npm
  • npm run dev — start Vite in dev mode
  • npm run build — build frontend assets for production

Environment variables

See .env for all variables. Common ones:

• Application
  • APP_NAME (default: FilamentApp)
  • APP_ENV (local, production, ...)
  • APP_DEBUG (true/false)
  • APP_URL (default: http://localhost)
  • APP_LOCALE, APP_FALLBACK_LOCALE
• Logging
  • LOG_CHANNEL (default: stack), LOG_LEVEL
• Database (MySQL by default)
  • DB_CONNECTION, DB_HOST, DB_PORT, DB_DATABASE, DB_USERNAME, DB_PASSWORD
• Cache/Queue/Session
  • CACHE_STORE=database
  • QUEUE_CONNECTION=database
  • SESSION_DRIVER=database, SESSION_LIFETIME
• Redis
  • REDIS_CLIENT=phpredis, REDIS_HOST, REDIS_PORT
• Mail
  • MAIL_MAILER=log, MAIL_HOST, MAIL_PORT, MAIL_USERNAME, MAIL_PASSWORD, MAIL_FROM_*
• AWS (only if you enable S3, etc.)
  • AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_DEFAULT_REGION, AWS_BUCKET
• Vite
  • VITE_APP_NAME (default mirrors APP_NAME)

Project structure (selected)

• app/ — application code (models, controllers, policies, jobs, etc.)
• bootstrap/ — framework bootstrap files
• config/ — application configuration
• database/ — migrations, factories, seeders
• public/ — public web root (entry: public/index.php)
• resources/ — Blade views, CSS, JS
  • resources/css/app.css — Tailwind entry
  • resources/js/app.js — JS entry (referenced by Vite)
  • resources/views/... — Blade templates (includes Livewire components)
• routes/
  • web.php — web routes
  • api.php — API routes
• tests/ — test suite (Pest)
• vite.config.js — Vite configuration
• artisan — Laravel CLI
• composer.json / package.json — dependencies and scripts

Development notes

• Vite HMR refresh is enabled via laravel-vite-plugin with inputs resources/css/app.css and resources/js/app.js.
• Sessions, cache, and queue default to database-backed stores. Ensure migrations are run.
• Jetstream is installed. The chosen Jetstream stack (Livewire vs Inertia) isn’t explicitly declared here — Livewire is present. See composer.json and resources/views for details.

Testing

Run the test suite:

php artisan test
# or
./vendor/bin/pest

You can create tests under tests/ using Pest’s syntax.

Deployment

• Build frontend assets:

  npm run build
  

• Ensure APP_ENV=production, APP_DEBUG=false, correct APP_URL, and proper cache/queue/mail configurations.
• Run database migrations on deploy:

  php artisan migrate --force
  

Docker (optional)

Laravel Sail is included as a dev dependency. If you prefer Docker, you can set up Sail. This repository does not include a prepared Sail config in this README.

Entry points

• HTTP: public/index.php (served via the web server or php artisan serve)
• CLI: artisan
• Frontend dev server: npm run dev (Vite)

TODOs / Unknowns

• Production deployment target and steps (server, PaaS, container registry) — TODO
• Domain and HTTPS/TLS configuration — TODO
• Mail provider and credentials for non‑log mailers — TODO
• Storage driver(s) for user uploads (local vs S3) — TODO
• Background jobs in production (e.g., Supervisor, Horizon) — TODO
• Any seeded demo data or default admin user — TODO

License

This project is open-sourced software licensed under the MIT license. See composer.json for the declared license.