Appearance

Laravel Inertia React Installation ​

You can install Email Builder with Laravel project using Inertia & React.

Requirements ​

Install Laravel Inertia ​

Ensure you have installed Laravel with Inertia & Vuejs or using (Laravel Vue Starter Kit)Laravel Inertia Docs or Inertiajs Docs for more info.

Composer Authentication ​

You need an API key to install PHP package(s) from the emailbuilder.dev repository. Composer supports storing this token in the auth.json file. Run following command to install composer credentials in project root auth.json file. Add --global flag, if you want to store globally (optional).

sh
composer config http-basic.composer.emailbuilder.dev <username> <api-token>
  • Replace <username> with your Email.
  • Replace <api-key> with your API key (token).

CAUTION

Add /auth.json to your .gitignore. Do not commit these credentials with source code.

API Token

Get your API token from Email Builder

Add Repository ​

To install packages from the emailbuilder.dev repository, add it to your project root composer.json file:

sh
composer config \
    repositories.emailbuilder \
    composer https://composer.emailbuilder.dev

Above command will add following to the composer.json file

json
// composer.json
{
    ...
    "repositories": {
        "emailbuilder": {
            "type": "composer",
            "url": "https://composer.emailbuilder.dev"
        }
    }
}

.test TLD for local ​

For better result we suggest to use <your-domain>.test domain for local development instead of localhost.

ini
# .env file
APP_URL=http://<example-domain>.test

Environment Variables ​

Ensure to add following environment variables to your .env file.

  • <token> Add API token.

  • Retrieve the api-prefix value from the apiPrefix parameter defined in the withRouting method inside bootstrap/app.php.

ini
EMAIL_BUILDER_TOKEN=<token>

# e.g. http://example.com/api
EMAIL_BUILDER_API_URL=http://<your-domain>/<api-prefix>

# e.g. deepseek, openai
EMAIL_BUILDER_AI_PROVIDER=<provider>

# API Key & Model
DEEPSEEK_API_KEY=<ai-provider-api-token>

# e.g. deepseek-chat
DEEPSEEK_MODEL=<ai-provider-model>

Install Laravel Sanctum ​

Email Builder UI communicate with backend via API. We need to install laravel/sanctum to protect our API routes. You are free to use other API auth libraries or methods. For this installation we will run following command to get Laravel Sanctum. Visit Laravel Sanctum Docs for more info.

sh
php artisan install:api

Javascript Dependencies ​

Javascript dependencies required to run interface. shadcn, @tanstack/react-table, axios are required to install. @tanstack/react-table and axios can be replaced with preferred alternatives after installation is finished.

  • Add npm repository for @apsonex-email-builder/react-core. Replace api-key with your api-key generated in emailbuilder.dev
sh
npm config set @apsonex-email-builder:registry https://npm-repos.emailbuilder.dev/ --location=project && \
    npm config set //npm-repos.emailbuilder.dev/:_authToken <api-key> --location=project

CAUTION

Add /.npmrc to your .gitignore. Do not commit these credentials with source code.

bash
npm install @tanstack/react-table axios @apsonex-email-builder/react-core && \
    npx shadcn@latest add table
bash
yarn add @tanstack/react-table axios @apsonex-email-builder/react-core && \
    yarn shadcn@latest add table
bash
pnpm add @tanstack/react-table axios @apsonex-email-builder/react-core && \
    pnpm dlx shadcn@latest add table
bash
bun add @tanstack/react-table axios @apsonex-email-builder/react-core && \
    bunx --bun shadcn@latest add table

Install Laravel Email Builder ​

Now we have added credentials to access repository, run composer require apsonex/email-builder-laravel to install the PHP package.

sh
composer require apsonex/email-builder-laravel

Run Installation Command ​

Installing all the required files will take so much time. But not to worry, We will scaffold for you required file so that you get a good start. Simply run php artisan email-builder:laravel-install

sh
php artisan email-builder:install

email-builder:install command will add bunch of files in you Laravel project.

Post Installation ​

After installation is done, we need to tell Laravel about the new files. Perform following post installation step to get Email Builder up and running.

Routes Setup ​

Installation has created routes/email-builder-api.php & routes/email-builder-web.php files in routes directory. We need to make aware Laravel about those files. In project bootstrap/app.php file, we need to install the newly created routes file as follows. Also add stateful access to backend via Middleware for frontend API.

php
<?php

use Illuminate\Foundation\Application;
use App\Http\Middleware\HandleAppearance;
use App\Http\Middleware\HandleInertiaRequests;
use Illuminate\Foundation\Configuration\Exceptions;
use Illuminate\Foundation\Configuration\Middleware;
use Illuminate\Http\Middleware\AddLinkHeadersForPreloadedAssets;

return Application::configure(basePath: dirname(__DIR__))
    ->withRouting(
        web: [
            __DIR__ . '/../routes/web.php',
            __DIR__ . '/../routes/email-builder-web.php', 
        ],
        api: [
            __DIR__ . '/../routes/api.php',
            __DIR__ . '/../routes/email-builder-api.php', 
        ],
        commands: __DIR__ . '/../routes/console.php',
        health: '/up',
        apiPrefix: 'api', // optional
    )
    ->withMiddleware(function (Middleware $middleware) {
        $middleware->encryptCookies(except: ['appearance', 'sidebar_state']);

        $middleware->statefulApi(); 

        $middleware->web(append: [
            HandleAppearance::class,
            HandleInertiaRequests::class,
            AddLinkHeadersForPreloadedAssets::class,
        ]);
    })
    ->withExceptions(function (Exceptions $exceptions) {
        //
    })->create();

Environment Variables ​

Ensure to add following environment variables to your .env file.

  • Retrieve the api-prefix value from the apiPrefix parameter defined in the withRouting method inside bootstrap/app.php.
ini
EMAIL_BUILDER_TOKEN=<token>

# e.g. https://example.com/api
EMAIL_BUILDER_API_URL=<your-domain>/<api-prefix>

# e.g. deepseek
EMAIL_BUILDER_AI_PROVIDER=<provider>

# e.g. sk-abc...
DEEPSEEK_API_KEY=<ai-provider-api-token>

# e.g. deepseek-chat
DEEPSEEK_MODEL=<ai-provider-model>

Migrate ​

Ensure run migrations

sh
php artisan migrate

Vite Optimize Dependencies ​

Exclude @apsonex-email-builder/react-core from dependency optimization to ensure proper handling during development. Mark the package to be loaded as source instead of being pre-bundled.

js
export default defineConfig({
    optimizeDeps: {
        exclude: [
            '@apsonex-email-builder/react-core',
        ],
    },
    {...}
});

Generate Routes - Laravel Wayfinder ​

Run php artisan wayfinder:generate command to sync Laravel routes with frontend by generating typed helpers and definitions. This will make available following routes to UI: @/routes/email-templates and @/routes/email-builder-leads.

sh
php artisan wayfinder:generate

UI Access ​

Add ui access to sidebar menu items. Visit resources/js/components/app-sidebar.tsx file and update mainNavItems items.

js
{...}
import { dashboard } from '@/routes';
import emailTemplates from '@/routes/email-templates'; 
import emailReceivables from '@/routes/email-receivables'; 
{...}
import { BookOpen, Folder, LayoutGrid } from 'lucide-react'; 
import { BookOpen, Folder, LayoutGrid, AtSign, Users } from 'lucide-react'; 
{...}

const mainNavItems: NavItem[] = [
    {
        title: 'Dashboard',
        href: dashboard(),
        icon: LayoutGrid,
    },
    { 
        title: 'Email Templates', 
        href: emailTemplates.index().url, 
        icon: AtSign, 
    }, 
    { 
        title: 'Email Receivables', 
        href: emailReceivables.index().url, 
        icon: Users, 
    }, 
];

{...}

Run NPM Install ​

Install NPM Packages

bash
npm install
bash
yarn install
bash
pnpm install
bash
bun install

CSS Variables ​

Email Builder is built on top of Shadcn. Add following css-variables to your project style. Change variable to match your branding. Dark theme support is coming soon.

css
:root {
    --background: oklch(1 0 0);
    --foreground: oklch(0.145 0 0);
    --card: oklch(1 0 0);
    --card-foreground: oklch(0.145 0 0);
    --popover: oklch(1 0 0);
    --popover-foreground: oklch(0.145 0 0);
    --primary: oklch(0.205 0 0);
    --primary-foreground: oklch(0.985 0 0);
    --secondary: oklch(0.97 0 0);
    --secondary-foreground: oklch(0.205 0 0);
    --muted: oklch(0.97 0 0);
    --muted-foreground: oklch(0.556 0 0);
    --accent: oklch(0.97 0 0);
    --accent-foreground: oklch(0.205 0 0);
    --destructive: oklch(0.577 0.245 27.325);
    --destructive-foreground: oklch(0.577 0.245 27.325);
    --border: oklch(0.922 0 0);
    --input: oklch(0.922 0 0);
    --ring: oklch(0.708 0 0);
    --chart-1: oklch(0.646 0.222 41.116);
    --chart-2: oklch(0.6 0.118 184.704);
    --chart-3: oklch(0.398 0.07 227.392);
    --chart-4: oklch(0.828 0.189 84.429);
    --chart-5: oklch(0.769 0.188 70.08);
    --radius: 0.625rem;
    --sidebar: oklch(0.985 0 0);
    --sidebar-foreground: oklch(0.145 0 0);
    --sidebar-primary: oklch(0.205 0 0);
    --sidebar-primary-foreground: oklch(0.985 0 0);
    --sidebar-accent: oklch(0.97 0 0);
    --sidebar-accent-foreground: oklch(0.205 0 0);
    --sidebar-border: oklch(0.922 0 0);
    --sidebar-ring: oklch(0.708 0 0);
}

For more info visit Shadcn-Vue

Tailwind CSS ​

Tailwind CSS need content location to compile css for Email Builder.

css
/* app.css */
@source '../../vendor/apsonex/email-builder-laravel/resources/dist/**/*.js';
css
/* app.css */
@source '../../vendor/apsonex/email-builder-laravel/resources/dist/**/*.js';
css
/* app.css */
@source '../../vendor/apsonex/email-builder-laravel/resources/dist/**/*.js';
css
/* app.css */
@source '../../vendor/apsonex/email-builder-laravel/resources/dist/**/*.js';

Installation Details ​

Installation will generate required files to run email builder. Lets see what files it will generate and options to customize those files.

Service Provider ​

It will create EmailBuilderServiceProvider.php which will provide necessary date to frontend via Inertia::share().

php
<?php

namespace App\Providers;

use {...}

class EmailBuilderServiceProvider extends ServiceProvider
{
    {...}

    public function boot(): void
    {
        \Inertia\Inertia::share('email_builder', function (Request $request) {
            return [
                {...}
            ];
        });
    }
}

Route Files ​

Installation will generate two route files. routes/email-builder-api.php and routes/email-builder-web.php.

  • routes/email-builder-api.php is responsible to provide necessary api access to email builder. Make sure you have secured it with auth. In following example we are using auth:sanctum middleware to protect api routes.
php
// routes/email-builder-api.php
<?php

{...}

Route::middleware(['auth:sanctum', 'verified'])->prefix('apsonex-email-builder')->as('email-builder.')->group(function () {
    // Config To initialize
    Route::get('/initialize-config', BaseController\InitializeController::class)->name('initialize-config');

    {...}
});
  • routes/email-builder-web.php is responsible to provide Email Builder UI access to user. You can design and broadcast email template to multiple users or leads at once. But if you want to send quick email to single user or lead, just use quick-send example below. Customize according to your need.
php
// routes/email-builder-web.php
{...}

/** Email Templates Routes */
Route::middleware(['auth'])
    ->prefix('/dashboard')
    ->group(function () {

        // comments {...}
        Route::get('/email-templates', [BaseController\ReactUiController::class, 'index'])->name('email-templates.index');
        {...}

        // comments {...}
        Route::as('email-builder-leads.')->prefix('email-builder-leads')->group(function () {
            Route::get('/', [BaseController\QuickSendEmailReactController::class, 'index'])->name('index');
            {...}
        });
    });

NPM Package @apsonex-email-builder/react-core ​

Installation will add @apsonex-email-builder/react-core package to you package.json file if it does't exist.

Files Updated Or Added ​

Email builder will generate following files to integrate Email Builder to you web app. You can further customize according to your needs.

tree
project-root/
├─ 🗂️ app
│  ├─ 🗂️ EmailBuilder
│  │   ├─ 🗂️ Enums
│  │   │  ├─ EmailBuilderContextKey.php
│  │   │  └─ EmailBuilderRoute.php
│  │   ├─ 🗂️ PlaceholderCasts
│  │   │  ├─ Date.php
│  │   │  └─ {...} // Other Placeholder Casts
│  │   └─ 🗂️ Placeholders
│  │      ├─ BusinessPlaceholders.php
│  │      └─ {...} // Other Placeholders
│  └─ 🗂️ Providers
│     └─ EmailBuilderServiceProvider.php
├─ 🗂️ bootstrap
│  └─ app.php
├─ 🗂️ database
│  └─ 🗂️ migrations
│     └─ <timestamp>_create_email_builder_tables.php
├─ 🗂️ resources
│  └─ 🗂️ js
│     ├─ 🗂️ configs
│     │  └─ email-builder-config.ts
│     ├─ 🗂️ lib
│     │  └─ apsonex-utils.ts
│     └─ 🗂️ pages
│        ├─ email-builder-leads
│        │  ├─ 🗂️ _partials/
│        │  │  ├─ data-table.tsx
│        │  │  └─ dropdown-action.tsx
│        │  ├─ index.tsx
│        │  └─ quick-send.tsx
│        └─ 🗂️ email-templates
│           ├─ 🗂️ _partials
│           │  ├─ data-table.tsx
│           │  └─ dropdown-action.tsx
│           ├─ create.tsx
│           ├─ edit.tsx
│           ├─ index.tsx
│           └─ manage.tsx
└─ 🗂️ routes
   ├─ email-builder-api.php
   └─ email-builder-web.php

Copyright © 2025 Apsonex Inc.