npm package: @laravelui5/core
Description: A reusable tools library for OpenUI5 applications, including session and HTTP utilities.
Author: Michael Gerzabek
Latest version: 4.3.2

# @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:

```bash
npm install @laravelui5/core --save
````

Or for local development via workspace:

```json
{
  "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](https://github.com/SAP/ui5-tooling/blob/main/rfcs/0006-local-dependency-resolution.md))

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

## Integration in a UI5 Component

In your `Component.ts` initialize the Facade.

```ts
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:

```json
{
  "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:

```bash
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

```bash
npm login
```

Then publish the package.

```bash

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](https://sap.github.io/ui5-tooling/)
* [UI5 Workspace RFC](https://github.com/SAP/ui5-tooling/blob/main/rfcs/0006-local-dependency-resolution.md)
* [UI5 Types on npm (@openui5/types)](https://www.npmjs.com/package/@openui5/types)
* [ui5-tooling-transpile (not used)](https://github.com/petermuessig/ui5-tooling-transpile)
* [Why TypeScript is hard in UI5](https://github.com/SAP/ui5-tooling/issues/996)

## Credits

Developed by [Michael Gerzabek](https://github.com/mgerzabek)