Getting Started

Welcome to LaravelUi5 — your toolkit for building UI5 apps inside a Laravel project.

This guide has two parts that stay cleanly apart:

1. Install LaravelUi5 Core — one-time, project-level setup. After this, Core runs and the ui5:* commands work for any app you build.
2. Assemble & run the launchpad-app — scaffold a ready-made dashboard app and wire it into your host.

No npm, no UI5 CLI, no front-end build step.

Part 1 — Install LaravelUi5 Core

Project-level setup. Do this once per Laravel app (Laravel 13).

Add the package source and install

You'll need a Composer token. Reading the docs is free. Installing needs a free account: it gives you a named installation and its token for composer require. Create your free account →

Point Composer at the LaravelUi5 package registry, hand it your install token, then require Core:

composer config repositories.pragmatiqu composer https://packages.pragmatiqu.io
composer config --global http-basic.packages.pragmatiqu.io your-email@example.com YOUR-INSTALL-TOKEN
composer require laravelui5/core

The registry is private, so the second line is not optional — without it the third one fails, because the registry answers 401 and asks for credentials. The token is the password; the username is the email on your account. The portal hands you that second line already filled in when you mint a token — copy, paste, done.

--global puts the credential in ~/.composer/auth.json, where it belongs to your machine rather than to one checkout; without the flag it lands in an auth.json beside your composer.json, which works but is one more file to keep out of version control. See Installation for the long form.

This pulls in the ui5:* artisan commands and the LaravelUi5 runtime. The Ui5CoreServiceProvider is auto-discovered — you don't register it by hand.

Swap in the UI5-aware CSRF middleware

UI5/OData uses the SAP CSRF-token handshake, so Core ships a drop-in replacement for Laravel's request-forgery middleware. This is a Core-level concern — it makes every UI5 and OData request work, independent of any individual app — so configure it now, right after install. In bootstrap/app.php:

use Illuminate\Foundation\Http\Middleware\PreventRequestForgery;
use LaravelUi5\Core\Http\Middleware\VerifyCsrfToken;

return Application::configure(basePath: dirname(__DIR__))
    // ...
    ->withMiddleware(function (Middleware $middleware) {
        $middleware->web(replace: [
            PreventRequestForgery::class => VerifyCsrfToken::class,
        ]);
    })
    // ...

That's the only middleware edit you ever need — Core applies its UI5 and OData middleware (context resolution, auth, CSRF-token fetch) to its own route groups automatically.

Laravel 12 and earlier

PreventRequestForgery is the Laravel 13 name. On Laravel 12 the class is Illuminate\Foundation\Http\Middleware\ValidateCsrfToken; on Laravel 11 and earlier it is VerifyCsrfToken. Replace whichever one your version registers in the web group. LaravelUi5 Core targets Laravel 13.

Publish the config

php artisan vendor:publish --tag=ui5-config

This drops config/ui5.php, where you'll list your apps in Part 2.

Core is now installed and ready. You could scaffold a fresh app with php artisan ui5:app MyApp --create from here — plus the four identity options that name your vendor, which the generator does not guess (see App). The rest of this guide uses the ready-made launchpad blueprint.

plannedUntil that lands the options have defaults, and they are ours — pass them anyway.

Part 2 — Assemble & run the launchpad-app

App-level. Everything here is about one specific app — scaffold it, register it, serve it.

Assemble the app

php artisan ui5:assemble launchpad-app

This scaffolds a self-contained app at ui5/Showcase and reports every file it writes. The blueprint produces a ShowcaseApp / ShowcaseModule pair (PHP namespace Showcase, UI5 namespace com.example.showcase), a pre-wired SalesOverview dashboard and everything on it: three groups holding three KPI tiles, five charts and two cards — already wired together. You own every generated file.

Register the app with your host

The app lives in your tree but isn't loaded yet. It is a Composer package — ui5/Showcase/composer.json already declares the Showcase\ autoload root and the app's service provider — so the host loads it as a local path package. Two commands, then one edit.

1. Add the package — register a path repository for the app and require it, the same way you registered our package registry above:

composer config repositories.showcase path ui5/Showcase
composer require example/showcase:@dev

Let Composer write these rather than editing composer.json by hand. Your repositories section already holds the package registry from Part 1, and Composer accepts two shapes for that section — a named block or a plain list. The section holds one or the other, so pasting in the shape it isn't replaces what is there and takes the pragmatiqu entry with it; the next resolve then fails to find laravelui5/core at all. Composer keeps the shape consistent whichever way you started, and puts the path repository first so your local app outranks the registry.

composer require installs the package in the same step, so there is no separate update to run afterwards. The result in composer.json, for reference:

"repositories": {
    "showcase": { "type": "path", "url": "ui5/Showcase" },
    "pragmatiqu": { "type": "composer", "url": "https://packages.pragmatiqu.io" }
},
"require": {
    "example/showcase": "@dev"
}

One entry per app, naming the directory exactly. Composer also accepts a wildcard ("url": "ui5/*"), which picks up every app under ui5/. It saves a command, but it turns "which apps does this host load?" into a question you answer by listing a directory rather than by reading the manifest. We name them one by one.

2. Register the module — in config/ui5.php, add the module class to the modules array:

'modules' => [
    \Showcase\ShowcaseModule::class,
],

This edit stays manual by design: only modules listed here are visible and supported. It is a product decision about scope, not wiring.

Path repositories symlink by default, so ui5/Showcase/ stays live — edit src/, reload, done.

Nothing to dump

composer require already installed the app. Reaching for composer dump-autoload instead does nothing here: it only regenerates maps for what is already in your lock file, and the app is not in it yet. The host then fails to boot with UI5 module class … does not exist — a message that points at the registry when the fault is the autoloader.

What you no longer do

No PSR-4 entry in the host's autoload, and no line in bootstrap/providers.php. The generated ui5/Showcase/composer.json carries both — the autoload root, and ShowcaseServiceProvider under extra.laravel.providers, which Laravel's package discovery registers for you. (That provider is where container bindings your tiles and charts need will go.)

Load ECharts for the dashboard charts

The dashboard's charts render with ECharts, which the browser must load before UI5 boots. Core ships a ready-made bootstrap <head> snippet that pulls it from a CDN — publish it:

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

This drops resources/views/ui5/head.blade.php (and a foot.blade.php) into your own views folder; Core's bootstrap template includes them automatically via @includeIf('ui5.head') — no namespace, no further wiring. Edit them freely; they are yours. (A Core app without charts doesn't need this step.)

Open in browser

Start the dev server:

php artisan serve

The app's entry point is ui5/app/{namespace}@{version}/index.html, with the namespace dots written as slashes:

http://localhost:8000/ui5/app/com/example/showcase@1.0.0/index.html

You should see the Sales Overview dashboard — three groups of KPI tiles, charts and cards — running. No extra tooling, no front-end build, just Laravel and UI5 working together.

⚠️ Heads-up

For production, use dedicated UI5 projects for your apps!

The self-contained ui5:assemble setup is great for quick starts and learning. For real-world apps, we recommend the workspace-based setup using the UI5 CLI and build tools, and shipping each app as a Composer package.

When you're ready:

• Use the official UI5 setup and build tooling based on ui5.yaml, and organize your apps as modular Composer packages — see Ui5App and its source strategies (WorkspaceStrategy reads webapp/ live during development, PackageStrategy serves the built output).
• Add more artifact types — reports, cards, tiles, charts, actions — with the ui5:* generators. The Backend overview lists them all.