Modules

Modules are self-contained feature packages that you install directly into your repository. Unlike traditional Composer packages, module code becomes part of your codebase, giving you complete ownership and customization freedom.

What Are Modules?

Think of modules like building blocks you copy into your project rather than linking to external packages.

Traditional Approach (Vendor Packages)

composer require vendor/auth-package
# → Code stays in vendor/
# → You can't modify it
# → Updates can break your customizations

Saucebase Approach (Copy-and-Own)

composer require saucebase/auth
# → Code is copied to modules/Auth/
# → You own it completely
# → Modify freely without maintenance burden

Philosophy

When you install a module, you're not depending on it—you're acquiring it. The code is yours from day one.

Available Modules

🔐

Auth

Complete authentication system with social login support for Google and GitHub. Includes registration, login, password reset, and OAuth integration.

View on GitHub

⚙️

Settings

User and system settings management with a flexible configuration system. Manage user preferences and application-wide settings.

View on GitHub

Coming Soon

💳

Billing

Subscription and payment management with Stripe integration. Handle plans, invoices, and customer billing.

In Development

Coming Soon

👥

Teams

Multi-tenant team management with role-based permissions. Collaborate with team members on shared resources.

In Development

Coming Soon

🔔

Notifications

Multi-channel notification system supporting email, SMS, and in-app notifications with queue support.

In Development

Coming Soon

🔌

API

RESTful API foundation with Laravel Sanctum authentication and API token management.

In Development

Installing Modules

Installation Steps

Follow these steps in order to install any module:

# 1. Install the module via Composer
composer require saucebase/auth

# 2. Regenerate autoload files
composer dump-autoload

# 3. Enable the module
php artisan module:enable Auth

# 4. Run migrations and seeders
php artisan module:migrate Auth --seed

# 5. Build frontend assets
npm run build

What each command does:

composer require - Downloads the module and adds it to composer.json
composer dump-autoload - Regenerates autoloader to include new module classes
module:enable - Marks the module as enabled in modules_statuses.json
module:migrate --seed - Runs database migrations and seeds sample data
npm run build - Rebuilds frontend assets to include module JavaScript/CSS

Docker Environment

If using Docker:

# Install via Composer (on host machine)
composer require saucebase/auth
composer dump-autoload

# Enable and migrate (inside Docker container)
docker compose exec app php artisan module:enable Auth
docker compose exec app php artisan module:migrate Auth --seed

# Build assets (on host machine)
npm run build

Development Environment

If not using Docker:

composer require saucebase/auth
composer dump-autoload
php artisan module:enable Auth
php artisan module:migrate Auth --seed
npm run build

Managing Modules

Enable/Disable Modules

# Enable a module
php artisan module:enable Auth

# Disable a module
php artisan module:disable Auth

# List all modules
php artisan module:list

When you enable/disable modules, always rebuild frontend assets:

npm run build
# OR restart dev server
npm run dev

Module Status

Check which modules are enabled:

php artisan module:list

Or view modules_statuses.json:

modules_statuses.json
{
  "Auth": true,
  "Settings": true
}

Only modules with true are loaded.

Database Operations

# Run migrations
php artisan module:migrate Auth

# Rollback migrations
php artisan module:migrate-rollback Auth

# Refresh migrations (drop + re-run)
php artisan module:migrate-refresh Auth

# Seed data
php artisan module:seed Auth

# Migrate and seed together
php artisan module:migrate Auth --seed

Example: Installing Auth Module

The Auth module provides complete authentication with social login support.

Step 1: Install

composer require saucebase/auth
composer dump-autoload

Step 2: Enable and Migrate

php artisan module:enable Auth
php artisan module:migrate Auth --seed

Step 3: Build Assets

npm run build
# OR for development
npm run dev

Step 4: Configure OAuth (Optional)

Add to .env:

.env
GOOGLE_CLIENT_ID=your-google-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-google-client-secret

GITHUB_CLIENT_ID=your-github-client-id
GITHUB_CLIENT_SECRET=your-github-client-secret

Setup OAuth Apps:

Google: Google Cloud Console
GitHub: GitHub Developer Settings

What You Get

After installation, the Auth module provides:

✅ Login, registration, password reset flows
✅ OAuth integration (Google, GitHub via Laravel Socialite)
✅ Multiple provider connections per user
✅ Routes: /auth/login, /auth/register, /auth/forgot-password
✅ Admin panel access at /admin

Default Admin Credentials:

Email: chef@saucebase.dev
Password: secretsauce

warning

Change these credentials in production!

Module Structure

Each module is organized like a mini-application:

modules/Auth/
├── app/                          # Backend code
│   ├── Http/
│   │   ├── Controllers/
│   │   │   ├── LoginController.php
│   │   │   ├── RegisterController.php
│   │   │   └── SocialAuthController.php
│   │   ├── Middleware/
│   │   └── Requests/
│   ├── Models/
│   │   ├── User.php
│   │   └── SocialAccount.php
│   ├── Providers/
│   │   └── AuthServiceProvider.php
│   └── Services/
│       └── AuthService.php
├── config/
│   └── config.php                # Module configuration
├── database/
│   ├── factories/
│   ├── migrations/
│   │   └── 2024_01_01_000000_create_social_accounts_table.php
│   └── seeders/
│       └── AuthDatabaseSeeder.php
├── lang/
│   ├── en/
│   │   └── auth.php
│   └── pt_BR/
│       └── auth.php
├── resources/
│   ├── css/
│   │   └── app.css
│   └── js/
│       ├── app.ts                # Module setup hooks
│       ├── pages/
│       │   ├── Login.vue
│       │   ├── Register.vue
│       │   └── ForgotPassword.vue
│       └── components/
│           └── SocialLoginButton.vue
├── routes/
│   ├── web.php                   # Module routes
│   └── api.php
├── tests/
│   ├── Feature/
│   │   └── AuthTest.php
│   ├── Unit/
│   └── e2e/
│       └── login.spec.ts
├── vite.config.js                # Module assets for Vite
├── playwright.config.ts          # E2E test config
└── module.json                   # Module metadata

How Modules Work

1. Service Provider Registration

Module service providers are auto-loaded when enabled.

modules/Auth/app/Providers/AuthServiceProvider.php
class AuthServiceProvider extends ModuleServiceProvider
{
    protected string $name = 'Auth';
    protected string $nameLower = 'auth';

    public function register(): void
    {
        parent::register();
        // Register services, bindings
    }

    public function boot(): void
    {
        parent::boot();
        // Boot logic, event listeners
    }
}

The base ModuleServiceProvider handles:

Loading module translations
Loading module configuration
Registering module routes
Sharing Inertia data

2. Route Registration

Module routes are automatically loaded:

modules/Auth/routes/web.php
use Modules\Auth\app\Http\Controllers\LoginController;

Route::prefix('auth')->name('auth.')->group(function () {
    Route::get('login', [LoginController::class, 'show'])->name('login');
    Route::post('login', [LoginController::class, 'store']);
    Route::post('logout', [LoginController::class, 'destroy'])->name('logout');
});

Access routes at: https://localhost/auth/login

Modules can register navigation items by creating a routes/navigation.php file:

modules/Auth/routes/navigation.php
use Spatie\Navigation\Facades\Navigation;
use Spatie\Navigation\Section;

Navigation::add('Log out', '#', function (Section $section) {
    $section->attributes([
        'group' => 'user',
        'action' => 'logout',
        'slug' => 'logout',
        'order' => 100,
    ]);
});

Navigation is automatically loaded when the module is enabled. See Navigation for details.

4. Frontend Integration

Module pages use namespace syntax in Inertia:

modules/Auth/app/Http/Controllers/LoginController.php
public function show()
{
    return inertia('Auth::Login'); // Namespace syntax!
}

This resolves to: modules/Auth/resources/js/pages/Login.vue

5. Module Lifecycle Hooks

Modules can export setup hooks:

modules/Auth/resources/js/app.ts
export default {
    setup(app) {
        // Called before Vue app mounts
        // Register components, plugins, etc.
        console.log('Auth module setup');
    },

    afterMount(app) {
        // Called after Vue app mounts
        // Initialize services that need DOM
        console.log('Auth module mounted');
    },
};

Customizing Modules

Since modules are part of your codebase, customize freely:

modules/Auth/resources/js/pages/Login.vue
<script setup lang="ts">
// Add your custom logic
import { useCustomAuth } from '@/composables/useCustomAuth';

const { login } = useCustomAuth();
</script>

<template>
  <div>
    <!-- Customize the UI completely -->
    <h1>My Custom Login Page</h1>
    <!-- ... -->
  </div>
</template>

Example: Add Custom Field to Registration

Add migration:

php artisan make:migration add_phone_to_users --path=modules/Auth/database/migrations

Schema::table('users', function (Blueprint $table) {
    $table->string('phone')->nullable();
});

Update form request:

modules/Auth/app/Http/Requests/RegisterRequest.php
public function rules(): array
{
    return [
        'name' => ['required', 'string', 'max:255'],
        'email' => ['required', 'email', 'unique:users'],
        'phone' => ['nullable', 'string', 'max:20'], // Added
        'password' => ['required', 'confirmed', 'min:8'],
    ];
}

Update Vue component:

modules/Auth/resources/js/pages/Register.vue
<template>
  <form @submit.prevent="submit">
    <!-- ... existing fields ... -->

    <!-- Add phone field -->
    <Input
      v-model="form.phone"
      type="tel"
      label="Phone"
    />

    <!-- ... -->
  </form>
</template>

That's it! No forking, no maintaining patches. The code is yours.

Removing Modules

To completely remove a module:

# 1. Disable the module
php artisan module:disable Auth

# 2. Rollback migrations (if desired)
php artisan module:migrate-rollback Auth

# 3. Remove from Composer
composer remove saucebase/auth

# 4. Delete the directory
rm -rf modules/Auth

# 5. Rebuild assets
npm run build

Troubleshooting

Module Not Found

Symptoms: Class 'Modules\Auth\...' not found

Solution:

composer dump-autoload
php artisan optimize:clear

Module Routes Not Working

Check:

Module is enabled: php artisan module:list
Routes are registered: php artisan route:list --name=auth
Service provider is loaded

Fix:

php artisan module:enable Auth
php artisan optimize:clear

Frontend Assets Not Loading

Symptoms: Module pages show blank or 404

Solution:

npm run build
# OR restart dev server
npm run dev

Migrations Not Running

Symptoms: Tables don't exist

Solution:

php artisan module:migrate Auth
# Check status
php artisan module:migrate-status Auth

Creating Custom Modules

Creating your own module follows the same structure as built-in modules. You can use the module generator or manually create the structure. Documentation for creating custom modules is coming soon.

Next Steps

Routing - Learn about routing in Saucebase
SSR - Server-side rendering per page
Navigation - Build navigation menus

Modules are the heart of Saucebase. Install what you need, customize freely, and own your code.

What Are Modules?​

Traditional Approach (Vendor Packages)​

Saucebase Approach (Copy-and-Own)​

Available Modules​

Auth

Settings

Billing

Teams

Notifications

API

Installing Modules​

Installation Steps​

Docker Environment​

Development Environment​

Managing Modules​

Enable/Disable Modules​

Module Status​

Database Operations​

Example: Installing Auth Module​

Step 1: Install​

Step 2: Enable and Migrate​

Step 3: Build Assets​

Step 4: Configure OAuth (Optional)​

What You Get​

Module Structure​

How Modules Work​

1. Service Provider Registration​

2. Route Registration​

3. Navigation Registration​

4. Frontend Integration​

5. Module Lifecycle Hooks​

Customizing Modules​

Example: Customize Login Page​

Example: Add Custom Field to Registration​

Removing Modules​

Troubleshooting​

Module Not Found​

Module Routes Not Working​

Frontend Assets Not Loading​

Migrations Not Running​

Creating Custom Modules​

Next Steps​

What Are Modules?

Traditional Approach (Vendor Packages)

Saucebase Approach (Copy-and-Own)

Available Modules

Installing Modules

Installation Steps

Docker Environment

Development Environment

Managing Modules

Enable/Disable Modules

Module Status

Database Operations

Example: Installing Auth Module

Step 1: Install

Step 2: Enable and Migrate

Step 3: Build Assets

Step 4: Configure OAuth (Optional)

What You Get

Module Structure

How Modules Work

1. Service Provider Registration

2. Route Registration

3. Navigation Registration

4. Frontend Integration

5. Module Lifecycle Hooks

Customizing Modules

Example: Customize Login Page

Example: Add Custom Field to Registration

Removing Modules

Troubleshooting

Module Not Found

Module Routes Not Working

Frontend Assets Not Loading

Migrations Not Running

Creating Custom Modules

Next Steps