Laravel + React Starter Kit

Introduction

This is a fork of the Laravel + React Starter Kit with my additional features and improvements. Such as:

• Authorization: Built-in support for user roles and permissions. See docs/authorization.md for more details.
• Authentication & Workos: In addition to Laravel's built-in authentication, WorkOS is integrated for SSO and OAuth flows.
• Sail Included: Docker support with Laravel Sail for easy local development.
• Admin Panel: Built with Filament for a beautiful and responsive admin interface.
• Laravel Debugbar: Integrated for debugging and profiling.
• Laravel Data & Typescript: Utilizes spatie/laravel-data for data handling and spatie/typescript-transformer for TypeScript support.
• Laravel Translatable & Translations: Fully translated into Hebrew & supports translatable columns with spatie/laravel-translatable
• MinIO & Media Library: For file uploads and media management.
• Blueprint: Uses laravel-shift/blueprint for rapid application development.
• Backup: Integrated with spatie/laravel-backup for easy backup management.
• Monitoring: Integrated with laravel-pulse, laravel-horizon, and log-viewer for comprehensive monitoring and logging.

And much more!

Requirements

From a Linux distro of your choice, you will need:

• Docker - Containerization platform.
• Docker Compose - Tool for defining and running multi-container Docker applications.
• Git - Version control system.
• Bun - JavaScript runtime.
• Node.js - JavaScript runtime environment.
• PHP 8.4 or higher and Composer

Getting Started

After the installation you can edit blueprint.yaml to define your application structure and features. You can use the Blueprint documentation to learn how to define your models, controllers, and other components.

Finally Create your models, controllers, and other components using Blueprint:

sail artisan blueprint:build

Installation

1. Fork the repository and clone it to your local machine:

   This will help you get changes merged back into the main repository.

   git clone <your-fork-url>
   cd <your-repo-name>

2. Install dependencies:

   sail composer install
   sail npm install # or `sail bun install`

3. Copy the .env.example file to .env:

   cp .env.example .env

4. Run app with Sail:

   # Don't forget to add the alias to your shell config file (e.g., .bashrc, .zshrc)
   # alias sail='sh $([ -f sail ] && echo sail || echo vendor/bin/sail)'
   sail up -d

5. Generate application key:

    sail artisan key:generate

6. Run migrations and seed the database:

   sail artisan migrate --seed

7. Run the development server:

   sail composer run dev

Debugger & Playground

The application includes the Laravel Debugbar for debugging and profiling.

You can use the Playground at http://localhost/playground and play with:

• The Controller - You can modify the controller to test different scenarios.
• The View - You can modify the view to test different scenarios.
• Playground Command - Run php artisan app:playground.

File Uploads w/ MinIO & Media Library

MinIO is used for file uploads. You can access the MinIO dashboard at localhost:9000 with the credentials:

• Access Key: sail
• Secret Key: password

In the laravel app you can use the package for managing files: spatie/laravel-medialibrary

Temporary Files

...

Note: laravel-medialibrary uses optimization packages. Install them with:

sudo apt install jpegoptim optipng pngquant gifsicle libavif-bin
npm install -g svgo # or `sudo snap install svgo`

Translations & Translatable Columns

The application is fully translated into Hebrew. The translation files are located in the lang/he directory and lang/he.json for JSON translations.

Use the package bottelet/translation-checker to check for missing translations, automatically generate translation with Google Translate using the command:

sail translations:check en --sort --translate-missing
#                       └─target: `en`, `he` or any other language

In addition, the spatie/laravel-translatable package is used to handle translatable columns in the database. You can define translatable attributes in your models like this:

use Spatie\Translatable\HasTranslations;  

class YourModel extends Model
{
    use HasTranslations;

    public $translatable = ['name', 'description'];
}

Laravel Data & Typescript

The application uses spatie/laravel-data for data handling and spatie/typescript-transformer for TypeScript support.

Use Laravel Data to create DTOs with single source of truth for validation rules, type safety, and serialization. This allows you to define your data structures in a clean and maintainable way.

Create a Data class with:

sail artisan make:data <DataClassName>

Then, generate the TypeScript types with:

sail artisan typescript:transform

This will generate TypeScript types in the resources/js/types/generated.d.ts file so you can use them in your the frontend.

You have Laravels's additional types such as Paginator, EnumTtait with usefull methods like toCollection() in resources/js/types/index.d.ts.

Validation

In addition to the default validation rules, We have added the following custom validation rule:

• Phone: Validates that the input is a valid phone number using the package propaganistas/laravel-phone.

Authentication & WorkOS

In addition to Laravel's built-in authentication, the application integrates with WorkOS for Single Sign-On (SSO) and OAuth flows.

You can enable it in the .env file:

Environment Variable	Description & How to get it
WORKOS_ENABLED	Enables or disables WorkOS SSO functionality. Set to true to enable, false to disable
WORKOS_CLIENT_ID	Your WorkOS application client ID. Get from your WorkOS dashboard under Applications → Your App
WORKOS_CLIENT_SECRET	Your WorkOS application client secret. Get from your WorkOS dashboard under Applications → Your App

Note: Make Sure to set redirect URIs in your WorkOS dashboard to match your application URLs.

• Redirect URIs: http://localhost/authenticate
• App homepage URL: http://localhost

Backup

The application uses spatie/laravel-backup for backup management. You can configure the backup settings in the .env file:

Environment Variable	Description
BACKUP_ENABLED	Enables or disables the backup functionality
BACKUP_DISK	Specifies the storage disk for backups (e.g., s3, local)
BACKUP_MAX_STORAGE	Maximum storage size in GB for backup retention
BACKUP_ARCHIVE_PASSWORD	Optional password to encrypt backup archives

You can also monitor the backup status using the BackupHealthWidget in the admin panel.

App Monitoring

The starter kit integrates with:

• Laravel Pulse for application health monitoring.
• Laravel Horizon for monitoring Redis queues.
• Log Viewer for viewing and managing log files.

Accessing Monitoring Tools: Only users with the access permission on the admin guard can access these tools.