@laravelui5/core

Shared frontend utilities for UI5 applications in local development.

This package provides a small, stable communication layer for UI5 applications that are developed independently of a Laravel host application.

In a full LaravelUi5 setup, the library is exposed as a UI5 resource by the host. During local UI5 development, this is not possible. In that case, the same library is consumed as a npm package and served via the UI5 tooling middleware instead.

No local PHP runtime is required. No build steps are introduced.

What this library is

• A lightweight helper library for UI5 applications
• Focused on HTTP communication with a Laravel backend
• Designed for the UI5 Tooling ecosystem (ui5 serve, ui5 build)
• Safe to use without custom transpilation or bundling
• Maintained as a long-term stable foundation

What this library is NOT

• Not a UI framework
• Not a UI5 component library
• Not a TypeScript transpilation solution
• Not tied to SAP BTP, CAP, or Fiori Launchpad

If you are looking for UI controls, layouts, or application scaffolding, this library is intentionally not the right place.

Installation

To consume the tools library in a UI5 application:

npm install @laravelui5/core --save

Or for local development via workspace:

{
  "dependencies": {
    "@laravelui5/core": "file:../ui5-core-lib"
  }
}

Use a local workspace dependency only when developing the library itself.

Basic Usage Model

The library exposes a single facade (LaravelUi5) which internally manages:

• A shared Connection instance
• CSRF token lifecycle
• Unified fetch behavior
• Centralized error handling

UI5 controllers and services never talk to fetch directly. All outbound communication goes through this layer.

Architecture & Design Decisions

This library is designed around UI5’s actual runtime constraints, not its ideal future.

Key principles:

• No transpilation
• No generated artifacts
• No hidden build steps
• No runtime indirection

What you develop locally is exactly what runs in production.

TypeScript Strategy

UI5 does not natively support TypeScript transpilation or .ts source loading for ui5-workspace.yaml related libraries.

We use the following approach:

• Source code is authored in vanilla JavaScript using sap.ui.define or ES6 modules.
• IntelliSense and type safety are enabled via handwritten .d.ts files.
• This avoids the overhead of custom build steps (tsc, ui5-tooling-transpile) while maintaining dev comfort.
• .ts and .d.ts files are not required at runtime, keeping output clean.

Why? Because:

• ui5 serve requires .js in src/
• ui5 build only considers src/, not dist/ (unless layered)
• ui5-workspace.yaml currently does not support resourcePath overrides (RFC 6)

Conclusion: We develop for UI5’s reality, not its ideal future.

Integration in a UI5 Component

In your Component.ts initialize the Facade.

import UIComponent from "sap/ui/core/UIComponent";
import LaravelUi5 from "com/laravelui5/core/LaravelUi5";

export default class Component extends UIComponent {

  public async init(): Promise<void> {
    // Call the base component's init function
    super.init();

    // Do the usual stuff…

    // …and finally start the Facade and the Router 
    LaravelUi5.init(this).then(() => {
      // Initialize router
      this.getRouter().initialize();
    }).catch((error) => {
      console.error(error);
    });
  }
}

That’s it. The facade must never be instantiated manually elsewhere.

All HTTP communication, CSRF handling and error normalization is now handled centrally by the library.

Versioning & Compatibility

This package follows the same version number as the LaravelUi5 Core (Composer) package.

• Major versions may introduce breaking changes
• Minor versions may add new helpers
• Patch versions contain bug fixes only

Frontend and backend versions are expected to match. Cross-version compatibility is intentionally not guaranteed.

Developing this Library Locally

This repository contains no build step.

• Source code lives in src/
• Type definitions live in types/
• No transpilation is performed
• No generated artifacts are committed

To test changes locally:

• Link the package via a file: dependency
• Run ui5 serve in the consuming app
• Reload the browser

If it works there, it will work in production.

Release Process (Maintainers only)

Releases are performed manually and intentionally, following the same version that is used for the corresponding Laravel (Composer) Core release.

Overview

A release consists of three explicit steps:

1. Set the version number
2. Verify the npm package contents
3. Publish to npm

npm itself acts as the official packaging and assembly mechanism.

1. Set the Version Number

Update the version field in package.json to match the released Core version:

{
  "version": "1.3.0"
}

The version is the single source of truth and must match the Composer package version.

2. Verify Package Contents

Before publishing, always verify what npm will include in the package:

npm pack --dry-run

This command shows the exact files that would be published, without uploading anything.

Ensure that only the intended files are included, typically:

• src/
• types/
• README.md
• LICENSE
• package.json

If the output looks correct, the package is ready to be published.

3. Publish the Package

Once verified, publish the package to npm. First login

npm login

Then publish the package.

npm publish

No additional build or transformation is performed. The published package is exactly what was verified in the previous step.

Related Resources

• UI5 Tooling Docs
• UI5 Workspace RFC
• UI5 Types on npm (@openui5/types)
• ui5-tooling-transpile (not used)
• Why TypeScript is hard in UI5

Credits

Developed by Michael Gerzabek