Sapui5 Cli

SAPUI5/OpenUI5 CLI Management Skill

Related Skills

• sap-dependency-security: Use for secure CLI/toolchain upgrades, lockfile hardening, and deterministic installs in UI5 tooling workflows

Table of Contents

• Overview
• When to Use This Skill
• Quick Start Workflow
• Project Types
• Bundled Resources

Overview

This skill provides comprehensive guidance for working with the UI5 CLI (UI5 Tooling), the official command-line interface for developing, building, and deploying SAPUI5 and OpenUI5 applications and libraries.

Current CLI Version: 4.0.55 (verified via npm on 2026-05-31) Node.js Requirements: v20.11.0+ or v22.0.0+ (v21 not supported) npm Requirements: v8.0.0+

When to Use This Skill

Use this skill when you need to:

• Initialize new UI5 projects or enable CLI support for existing projects
• Configure ui5.yaml for applications, libraries, theme-libraries, or modules
• Build UI5 projects with optimization, bundling, and minification
• Run local development servers with HTTP/2, SSL, and CSP support
• Extend build processes with custom tasks or server middleware
• Manage monorepo/workspace configurations with multiple UI5 projects
• Troubleshoot common UI5 CLI errors and build issues
• Migrate between CLI versions (v1 → v2 → v3 → v4)
• Optimize build performance and analyze dependencies

Quick Start Workflow

New Project Setup

# 1. Install UI5 CLI (choose one)
npm install --global @ui5/cli          # Global installation
npm install --save-dev @ui5/cli        # Project-level installation

# 2. Initialize project (if new)
npm init --yes                          # Initialize npm
ui5 init                                # Create ui5.yaml

# 3. Select framework variant
ui5 use openui5@latest                  # For OpenUI5
ui5 use sapui5@latest                   # For SAPUI5

# 4. Add framework libraries
ui5 add sap.ui.core sap.m sap.ui.table themelib_sap_fiori_3

# 5. Start development
ui5 serve                               # Start dev server
ui5 serve --open index.html            # Start and open browser

# 6. Build for production
ui5 build --all                         # Build with dependencies
ui5 build --clean-dest                  # Clean before building

Existing Project Setup

# 1. Enable CLI support
ui5 init

# 2. Configure framework (if ui5.yaml exists)
ui5 use openui5@latest                  # or sapui5@latest

# 3. Verify setup
ui5 tree                                # Show dependency tree
ui5 serve                               # Test development server

Project Types

UI5 CLI supports four project types, each with specific configurations:

1. Application

Standard UI5 applications with a webapp directory.

• Virtual path mapping: webapp/ → /
• Generates Component-preload.js when Component.js exists
• See templates/ui5.yaml.application for configuration template

2. Library

Reusable component libraries for sharing across projects.

• Virtual path mappings: src/ → /resources, test/ → /test-resources
• Requires namespace directory structure (e.g., src/my/company/library/)
• See templates/ui5.yaml.library for configuration template

3. Theme Library

Provides theming resources for libraries.

• Same virtual mappings as standard libraries
• Resources organized by namespace (e.g., my/library/themes/custom_theme/)
• See references/configuration.md for detailed configuration

4. Module

Third-party resources with flexible path mapping.

• Resources copied without modification
• Custom virtual-to-physical path mappings
• See references/project-structures.md for module configuration

Core Commands Reference

Project Initialization

ui5 init                                # Initialize UI5 CLI configuration
ui5 use <framework>[@version]           # Set framework (openui5/sapui5)
ui5 add <libraries...>                  # Add framework libraries
ui5 remove <libraries...>               # Remove framework libraries

Development

ui5 serve [options]                     # Start development server
  --port <number>                       # Specify port (default: 8080)
  --open <path>                         # Open browser to path
  --h2                                  # Enable HTTP/2
  --accept-remote-connections           # Allow non-localhost access

ui5 tree [options]                      # Display dependency tree
  --flat                                # Show flat list
  --level <number>                      # Limit tree depth

Building

ui5 build [child-command] [options]     # Build project
  preload                               # Create preload bundles (default)
  self-contained                        # Create standalone bundle
  jsdoc                                 # Generate JSDoc documentation

  --all                                 # Include all dependencies
  --include-dependency <names>          # Include specific dependencies
  --exclude-dependency <names>          # Exclude dependencies
  --dest <path>                         # Output directory (default: ./dist)
  --clean-dest                          # Clean destination before build
  --create-build-manifest               # Store build metadata
  --experimental-css-variables          # Generate CSS variable artifacts [experimental]

Configuration

ui5 config set <key> [value]            # Set configuration value
ui5 config get <key>                    # Get configuration value
ui5 config list                         # List all settings

# Common configurations
ui5 config set ui5DataDir /path/.ui5    # Change cache directory

Utility

ui5 versions                            # Display all module versions
ui5 --help                              # Display help
ui5 --version                           # Display version

For complete command reference, see references/cli-commands.md.

Configuration File Structure

Basic ui5.yaml Structure

specVersion: "4.0"                      # Specification version (required)
type: application                       # Project type (required)
metadata:
  name: my.project.name                 # Project name (required)
  copyright: "© ${currentYear} Company" # Optional copyright

framework:
  name: SAPUI5                          # OpenUI5 or SAPUI5
  version: "1.120.0"                    # Framework version
  libraries:
    - name: sap.ui.core
    - name: sap.m
    - name: sap.ui.table
    - name: themelib_sap_fiori_3
      optional: true                    # Optional library

resources:
  configuration:
    paths:
      webapp: webapp                    # Path mapping
    propertiesFileSourceEncoding: UTF-8 # Encoding (default: UTF-8)

builder:
  resources:
    excludes:
      - "index.html"                    # Exclude from build
      - "/resources/my/project/test/**"

server:
  settings:
    httpPort: 8080                      # HTTP port
    httpsPort: 8443                     # HTTPS port

For complete configuration reference, see references/configuration.md.

Progressive Disclosure: Detailed References

This main skill file provides essential workflows and quick reference. For detailed information on specific topics, refer to these reference files:

Core References

• `references/cli-commands.md`: Complete CLI command reference with all options and examples
• `references/configuration.md`: Comprehensive ui5.yaml configuration guide (includes workspace config)
• `references/project-structures.md`: Detailed project types with directory structures and build output styles

Advanced Topics

• `references/extensibility.md`: Custom tasks, middleware, and project shims with complete API documentation
• `references/filesystem-api.md`: Complete FileSystem API for custom task/middleware development
• `references/build-process.md`: Complete build process including tasks, minification, source maps, and bundling
• `references/server-features.md`: Complete server documentation with middleware stack, HTTP/2, SSL, and CSP
• `references/code-analysis.md`: Dependency analyzers, JSDoc generation, and code analysis features
• `references/es-support.md`: Complete ECMAScript version support, restrictions, and module format requirements

Performance & Troubleshooting

• `references/benchmarking.md`: Performance testing and benchmarking with hyperfine
• `references/migration-guides.md`: Complete version migration guides (v1→v2→v3→v4)
• `references/troubleshooting.md`: Common issues, errors, and solutions with exact error messages

Common Workflows

Workflow 1: Setting Up a New Application

When to use: Starting a new SAPUI5/OpenUI5 application from scratch.

Steps: 1. Initialize npm project: npm init --yes 2. Install UI5 CLI: npm install --save-dev @ui5/cli 3. Initialize UI5 configuration: ui5 init 4. Select framework: ui5 use sapui5@latest (or openui5@latest) 5. Add required libraries: ui5 add sap.ui.core sap.m themelib_sap_fiori_3 6. Create application structure (webapp/, Component.js, manifest.json) 7. Start development server: ui5 serve 8. Commit configuration: git add ui5.yaml package.json && git commit

Workflow 2: Enabling CLI for Existing Project

When to use: Adding UI5 CLI support to an existing UI5 project.

Steps: 1. Navigate to project root 2. Run ui5 init to create ui5.yaml 3. Configure framework: ui5 use sapui5@latest 4. Add libraries: ui5 add sap.ui.core sap.m sap.ui.table 5. Adjust ui5.yaml resources.configuration.paths if needed 6. Test with ui5 serve 7. Build with ui5 build --all

Workflow 3: Creating a Custom Build Task

When to use: Extending the build process with custom processing.

Steps: 1. Create task file (e.g., lib/tasks/customTask.js) 2. Implement task using Task API (see templates/custom-task-template.js) 3. Create task extension in ui5.yaml or separate file 4. Configure task in builder.customTasks section 5. Test with ui5 build 6. For details, see references/extensibility.md

Workflow 4: Setting Up a Workspace/Monorepo

When to use: Managing multiple related UI5 projects in a single repository.

Steps: 1. Create ui5-workspace.yaml in root project 2. Define workspace name and dependency resolutions 3. Point to local project directories using relative paths 4. Use --workspace <name> flag to activate specific workspace 5. Run ui5 tree to verify dependency resolution 6. For details, see references/configuration.md (workspace section)

Workflow 5: Migrating to UI5 CLI v4

When to use: Upgrading from UI5 CLI v3 to v4.

Prerequisites:

• Verify Node.js v20.11.0+ or v22.0.0+
• Verify npm v8.0.0+

Steps: 1. Update CLI: npm install --save-dev @ui5/cli@latest 2. Update specVersion in ui5.yaml to "4.0" 3. Review breaking changes in references/migration-guides.md 4. Remove usePredefineCalls bundle option if present 5. Update bundle sections to use async: true for modern loading 6. Test build: ui5 build --all 7. Test server: ui5 serve 8. Verify application functionality

Decision Trees

Framework Selection Decision

Question: Which framework should I use?

Does project need SAP-specific components (e.g., sap.ui.comp, sap.ushell)?
├─ YES → Use SAPUI5
│  └─ Command: ui5 use sapui5@latest
└─ NO → Can use OpenUI5
   └─ Command: ui5 use openui5@latest

Note: SAPUI5 projects can depend on OpenUI5, but not vice versa.

Build Type Decision

Question: Which build type should I use?

What is the deployment target?
├─ Standard deployment (with separate framework loading)
│  └─ Use: ui5 build --all
│
├─ Standalone deployment (single bundle with framework)
│  └─ Use: ui5 build self-contained --all
│
├─ Documentation generation
│  └─ Use: ui5 build jsdoc
│
└─ Development/testing (no build needed)
   └─ Use: ui5 serve

Custom Extension Decision

Question: Should I create a custom task or middleware?

What do you need to extend?
├─ Build process (modify/generate resources during build)
│  └─ Create custom task (see templates/custom-task-template.js)
│     Examples: Transpiling, image optimization, file generation
│
├─ Development server (modify requests/responses during dev)
│  └─ Create custom middleware (see templates/custom-middleware-template.js)
│     Examples: Proxying, authentication, dynamic content
│
└─ Third-party library configuration
   └─ Create project shim (see references/extensibility.md)
      Examples: Configuring non-UI5 npm packages

Templates

This skill provides working templates for common configurations:

• `templates/ui5.yaml.application`: Complete application configuration
• `templates/ui5.yaml.library`: Complete library configuration
• `templates/ui5-workspace.yaml`: Monorepo workspace setup
• `templates/custom-task-template.js`: Custom build task boilerplate
• `templates/custom-middleware-template.js`: Custom server middleware boilerplate

Important Notes

Specification Versions

UI5 CLI uses specification versions to manage features:

• 4.0: Current major version (verified CLI v4.0.55, requires Node.js v20.11.0+)
• 3.0-3.2: Compatible with CLI v3.0.0+
• 2.0-2.6: Compatible with CLI v2.0.0+
• 0.1-1.1: Legacy versions (automatic migration attempted)

Always use the latest specVersion for new projects.

Framework Version Requirements

• OpenUI5: Minimum version 1.52.5
• SAPUI5: Minimum version 1.76.0

Development vs. Build

Important: During development, always use ui5 serve instead of ui5 build. Building should only occur when deploying to production. The development server provides:

• Faster reload times
• On-the-fly resource processing
• Better debugging experience
• Automatic dependency resolution

Global vs. Local Installation

When both global and local UI5 CLI installations exist, the local version takes precedence automatically. This allows different projects to use different CLI versions.

Override behavior: UI5_CLI_NO_LOCAL=X ui5 serve

Cache Management

UI5 CLI caches framework versions in ~/.ui5/ (configurable via ui5DataDir).

Clear cache: rm -rf ~/.ui5/framework/

Known Issues & Limitations

ECMAScript Module Limitations

UI5 CLI does not support JavaScript modules with import/export syntax. All modules must use sap.ui.define format.

Unsupported:

import Module from './module.js';
export default MyClass;

Supported:

sap.ui.define(['./module'], function(Module) {
    return MyClass;
});

Template Literal Restrictions

Expressions in template literals cannot be used in:

• Dependency declarations
• Smart Template names
• Library initialization calls

Unsupported:

sap.ui.define([`modules/${moduleName}`], ...);  // Will fail

Bundling Restrictions (v4.0+)

JavaScript modules requiring 'top level scope' cannot be bundled as strings. They will be omitted from bundles with error logging.

Manifest Version Compatibility

For UI5 1.71, manifest _version property must be ≤ 1.17.0 for supportedLocales generation. Update manifest version to match UI5 framework version.

Troubleshooting Quick Reference

For detailed troubleshooting, see references/troubleshooting.md.

Common Issues

Issue: ERR_SSL_PROTOCOL_ERROR in Chrome when accessing HTTP server

Solution: Chrome enforces HTTPS via HSTS. Clear HSTS settings: 1. Navigate to chrome://net-internals/#hsts 2. Enter domain (e.g., localhost) 3. Click "Delete"

Issue: Excessive disk space in ~/.ui5/

Solution: Clear cached framework versions:

rm -rf ~/.ui5/framework/

Issue: Build fails with "TypeError: invalid input"

Solution: Check manifest _version compatibility with UI5 framework version. For UI5 1.71, use manifest version ≤ 1.17.0.

Issue: Custom task not executing

Solution: Verify task configuration: 1. Check task is properly defined in ui5.yaml 2. Verify beforeTask or afterTask references valid task name 3. Check task file exports async function with correct signature 4. Use ui5 build --verbose for detailed logging

Environment Variables

• `UI5_LOG_LVL`: Set log level (silent/error/warn/info/perf/verbose/silly)
• `UI5_DATA_DIR`: Override default data directory (~/.ui5)
• `UI5_CLI_NO_LOCAL`: Disable local CLI precedence (use global)

Examples:

UI5_LOG_LVL=verbose ui5 build
UI5_DATA_DIR=/custom/.ui5 ui5 serve

Best Practices

1. Always commit ui5.yaml and package.json to version control 2. Use local CLI installation for project consistency (--save-dev) 3. Pin framework versions for production builds 4. Use workspaces for monorepo setups instead of npm linking 5. Enable HTTP/2 during development (ui5 serve --h2) 6. Clean builds for production (ui5 build --clean-dest --all) 7. Validate configurations before committing (use validation scripts) 8. Test with multiple browsers when using CSP policies 9. Document custom tasks and middleware in project README 10. Keep CLI updated to benefit from latest features and fixes

Additional Resources

• Official Documentation: https://ui5.github.io/cli/stable/
• API Reference: https://ui5.github.io/cli/v4/api/
• JSON Schema: https://ui5.github.io/cli/schema/ui5.yaml.json
• GitHub Repository: https://github.com/SAP/ui5-tooling
• SAP Community: https://community.sap.com/
• npm Registry: https://www.npmjs.com/package/@ui5/cli

Bundled Resources

Reference Documentation

• references/cli-commands.md - Complete CLI command reference
• references/configuration.md - Configuration options and ui5.yaml
• references/project-structures.md - Project structure patterns
• references/server-features.md - Development server features
• references/build-process.md - Build process and optimization
• references/es-support.md - ES module support
• references/extensibility.md - Extensibility options
• references/code-analysis.md - Code analysis tools
• references/migration-guides.md - Migration from older versions
• references/troubleshooting.md - Common issues and solutions
• references/benchmarking.md - Performance benchmarking

Templates

• templates/ui5.yaml.application - Application configuration template
• templates/ui5.yaml.library - Library configuration template
• templates/ui5-workspace.yaml - Workspace configuration template
• templates/custom-task-template.js - Custom task boilerplate
• templates/custom-middleware-template.js - Custom middleware boilerplate

Version Information

• CLI Version Covered: 4.0.55+
• Last Updated: 2026-05-31
• Next Review: 2026-02-21 (Quarterly)

---

This skill follows official Anthropic Agent Skills best practices and SAP UI5 CLI documentation standards.

SAPUI5/OpenUI5 CLI Management Skill

Comprehensive skill for managing SAPUI5 and OpenUI5 projects using the UI5 Tooling CLI.

Capability Index

Auto-Trigger Keywords

This skill automatically activates when you mention any of these terms in your requests:

Core Technologies

ui5, sapui5, openui5, ui5-tooling, ui5-cli, @ui5/cli, ui5 tooling, ui5 cli, sap ui5, sap openui5

Configuration Files

ui5.yaml, ui5-workspace.yaml, ui5 yaml, ui5 workspace yaml, ui5.yml, ui5 configuration, ui5 config

CLI Commands

ui5 init, ui5 build, ui5 serve, ui5 add, ui5 remove, ui5 use, ui5 tree, ui5 config, ui5 versions

Framework Management

ui5 framework, openui5 framework, sapui5 framework, ui5 version, framework version, ui5 libraries, framework libraries

Project Types

ui5 application, ui5 library, ui5 theme library, theme-library, ui5 module, ui5 project, ui5 app

Build & Development

ui5 build process, ui5 builder, ui5 bundling, ui5 minification, ui5 preload, component preload, library preload, ui5 optimization, ui5 serve, ui5 development server, ui5 dev server, ui5 local server

Extensibility

ui5 custom task, ui5 custom middleware, ui5 extensibility, custom build task, custom server middleware, ui5 project shim, project shims, ui5 extension

Workspace & Dependencies

ui5 workspace, ui5 monorepo, ui5 dependencies, ui5 dependency tree, ui5 dependency resolution, ui5 multi project

Server Features

ui5 server, ui5 http2, ui5 https, ui5 ssl, ui5 csp, content security policy, ui5 cors, ui5 development server

Build Tasks

generateComponentPreload, generateLibraryPreload, buildThemes, minify, generateBundle, replaceVersion, replaceCopyright, escapeNonAsciiCharacters, generateVersionInfo

Configuration Sections

specVersion, spec version, metadata name, framework configuration, builder configuration, server settings, resources configuration, custom tasks, custom middleware, builder resources, component preload, library preload, cachebuster

Common Issues & Errors

ui5 build error, ui5 serve error, ui5 cli error, ui5 dependency error, ui5 framework error, ui5 build failed, ui5 cannot find, ui5 module not found, ERR_SSL_PROTOCOL_ERROR, ui5 HSTS, ui5 cache, ui5 home directory, .ui5 directory

Migration

ui5 cli migration, migrate to ui5 v4, migrate to ui5 v3, migrate to ui5 v2, ui5 cli upgrade, ui5 tooling migration, ui5 cli v4, ui5 cli v3, ui5 cli v2, ui5 breaking changes

Framework Variants

openui5 libraries, sapui5 libraries, sap.ui.core, sap.m, sap.ui.table, sap.ui.comp, sap.ushell, themelib_sap_fiori_3, themelib_sap_belize, themelib_sap_bluecrystal

Advanced Features

ui5 jsdoc, ui5 documentation, ui5 typescript, ui5 code analysis, ui5 benchmarking, ui5 performance, ui5 source maps, ui5 transpilation

Build Types

ui5 build preload, ui5 build self-contained, ui5 build jsdoc, standalone build, self-contained build, ui5 bundle

Path Mappings

webapp directory, src directory, test directory, resources path, test-resources path, virtual path, physical path, ui5 resources

Specification Versions

specVersion 4.0, specVersion 3.0, specVersion 2.0, specification version, spec version 4, spec version 3

Package Management

@ui5/builder, @ui5/server, @ui5/project, @ui5/fs, @ui5/logger, ui5 packages, ui5 modules

Node & npm

node version ui5, npm version ui5, ui5 node requirements, ui5 npm requirements

Environment Variables

UI5_LOG_LVL, UI5_DATA_DIR, UI5_CLI_NO_LOCAL, ui5 environment, ui5 env variables

Troubleshooting Terms

ui5 troubleshooting, ui5 debug, ui5 verbose, ui5 log level, ui5 cache clear, clear ui5 cache

Related Technologies

sap fiori, fiori elements, sap btp, sap cloud, sap cap, openui5 sdk, sapui5 sdk

File Extensions & Formats

.library file, library.js, manifest.json, Component.js, ui5.yaml schema, yaml validation

Skill Capabilities

This skill provides:

• Complete CLI command reference and usage patterns
• Configuration file templates for all project types
• Custom task and middleware examples
• Workspace/monorepo setup guidance
• Version migration guides (v1→v2→v3→v4)
• Troubleshooting common errors
• Build optimization strategies
• Framework setup (OpenUI5 vs SAPUI5)
• Progressive disclosure of detailed documentation

Quick Usage

# Initialize new project
ui5 init
ui5 use sapui5@latest
ui5 add sap.ui.core sap.m

# Development
ui5 serve --open index.html

# Production build
ui5 build --all --clean-dest

Documentation

See SKILL.md for complete documentation and reference files for detailed topics.

Version

• Skill Version: 1.0.0
• UI5 CLI Version: 4.0.55+
• Last Updated: 2026-05-31

License

GPL-3.0

UI5 CLI Benchmarking Guide

Official Documentation: https://ui5.github.io/cli/stable/pages/Benchmarking/

This reference provides comprehensive guidance for performance testing and benchmarking UI5 CLI operations using hyperfine.

Table of Contents

1. Overview 2. Tool: hyperfine 3. Setup 4. Basic Benchmarking 5. Comparative Benchmarking 6. Performance Metrics 7. Optimization Analysis 8. System Preparation 9. Best Practices 10. Example Workflows

---

Overview

Benchmarking UI5 CLI operations helps measure performance impacts of code changes, configuration adjustments, and optimization efforts.

Primary Use Cases:

• Measure build performance improvements
• Compare different UI5 CLI versions
• Evaluate custom task performance
• Identify performance bottlenecks
• Validate optimization efforts

Recommended Tool: hyperfine - "For benchmarking UI5 CLI we typically make use of the open source tool [hyperfine]"

---

Tool: hyperfine

What is hyperfine?

hyperfine is a command-line benchmarking tool that:

• Performs statistical warmup
• Runs multiple iterations
• Detects outliers
• Calculates mean, min, max, standard deviation
• Supports comparative benchmarks
• Exports results (JSON, Markdown, CSV)

Official Site: https://github.com/sharkdp/hyperfine

---

Installation

macOS (Homebrew):

brew install hyperfine

Ubuntu/Debian:

# Check https://github.com/sharkdp/hyperfine/releases for latest version
wget https://github.com/sharkdp/hyperfine/releases/download/v1.18.0/hyperfine_1.18.0_amd64.deb
sudo dpkg -i hyperfine_1.18.0_amd64.deb

Arch Linux:

pacman -S hyperfine

Windows (Scoop):

scoop install hyperfine

From Source (Cargo):

cargo install hyperfine

Verify Installation:

hyperfine --version

---

Setup

Prerequisites

1. UI5 CLI installed (globally or locally) 2. Test project (e.g., UI5 sample-app) 3. hyperfine installed 4. Stable system (connected to power, background apps closed)

---

Prepare Test Project

Clone Sample App:

git clone https://github.com/SAP/openui5-sample-app.git
cd openui5-sample-app
npm install

Verify Build Works:

ui5 build --all

---

Link Development Versions (Optional)

For testing UI5 CLI changes:

Clone and Link UI5 CLI:

# Clone repositories
git clone https://github.com/SAP/ui5-cli.git
git clone https://github.com/SAP/ui5-builder.git

# Install and link
cd ui5-cli
npm install
npm link

cd ../ui5-builder
npm install
npm link

# Link in test project
cd ../openui5-sample-app
npm link @ui5/cli
npm link @ui5/builder

---

Basic Benchmarking

Simple Build Benchmark

Command:

hyperfine 'ui5 build --all'

Output:

Benchmark 1: ui5 build --all
  Time (mean ± σ):      7.234 s ±  0.156 s    [User: 6.8 s, System: 0.4 s]
  Range (min … max):    7.042 s …  7.512 s    10 runs

Metrics Explained:

• Mean: Average execution time (7.234 s)
• σ (sigma): Standard deviation (±0.156 s)
• Range: Min to max observed times
• Runs: Number of iterations (default: auto)

---

With Warmup Runs

Purpose: Stabilize filesystem cache, JIT compiler

Command:

hyperfine --warmup 3 'ui5 build --all'

Explanation:

• Runs command 3 times before measurements
• Discards warmup results
• Ensures stable baseline

---

Custom Run Count

Command:

hyperfine --runs 20 'ui5 build --all'

When to Use:

• More runs = better statistical accuracy
• Fewer runs = faster benchmarking
• Default: hyperfine auto-determines optimal count

---

Preparation Command

Purpose: Clean build directory before each run

Command:

hyperfine \
  --prepare 'rm -rf dist' \
  'ui5 build --all'

Use Cases:

• Ensure clean builds
• Reset state between runs
• Simulate real-world scenarios

---

Comparative Benchmarking

Compare Two Commands

Baseline vs Optimized:

hyperfine \
  --warmup 2 \
  'ui5 build --all' \
  'ui5 build --all --exclude-task minify'

Output:

Benchmark 1: ui5 build --all
  Time (mean ± σ):      7.234 s ±  0.156 s    [User: 6.8 s, System: 0.4 s]
  Range (min … max):    7.042 s …  7.512 s    10 runs

Benchmark 2: ui5 build --all --exclude-task minify
  Time (mean ± σ):      5.123 s ±  0.102 s    [User: 4.9 s, System: 0.2 s]
  Range (min … max):    4.987 s …  5.301 s    10 runs

Summary
  'ui5 build --all --exclude-task minify' ran
    1.41 ± 0.04 times faster than 'ui5 build --all'

Analysis: Excluding minification is 41% faster

---

Compare Versions

Before and After Code Change:

# Checkout baseline
git checkout main
npm install
hyperfine --warmup 2 --export-json baseline.json 'ui5 build --all'

# Checkout optimized
git checkout feature/optimization
npm install
hyperfine --warmup 2 --export-json optimized.json 'ui5 build --all'

# Compare results
hyperfine --warmup 2 \
  --command-name "baseline" './node_modules/.bin/ui5 build --all' \
  --command-name "optimized" './node_modules/.bin/ui5 build --all'

---

Parameter Sweep

Test Different Options:

hyperfine \
  --parameter-scan workers 1 8 \
  'ui5 build --all --workers {workers}'

Explanation:

• Tests workers=1, workers=2, ..., workers=8
• Finds optimal parallelization
• Helps tune performance parameters

---

Performance Metrics

Key Metrics Captured

---

Understanding Variation

Low σ (< 5%): Consistent performance

Time (mean ± σ):  7.234 s ±  0.156 s  ← σ/mean = 2.2% (good!)

High σ (> 10%): Inconsistent, investigate causes

Time (mean ± σ):  7.234 s ±  0.892 s  ← σ/mean = 12.3% (investigate!)

Causes of High Variation:

• Background processes
• Thermal throttling
• Swapping/paging
• Network activity
• Inadequate warmup

---

Optimization Analysis

Calculating Improvement

Formula:

Improvement % = ((baseline - optimized) / baseline) * 100

Example:

Baseline:  10.0 s
Optimized:  7.0 s

Improvement = ((10.0 - 7.0) / 10.0) * 100 = 30%

Interpretation: Optimized version is 30% faster

---

Comparative Ratio

Formula:

Ratio = baseline / optimized

Example:

Baseline:  10.0 s
Optimized:  7.0 s

Ratio = 10.0 / 7.0 = 1.43

"Optimized ran 1.43 times faster"

---

Statistical Significance

Check σ Overlap:

Baseline:  10.0 s ± 0.2 s  (range: 9.8 - 10.2 s)
Optimized:  9.8 s ± 0.3 s  (range: 9.5 - 10.1 s)

Overlap: Yes → Difference may not be significant

No Overlap:

Baseline:  10.0 s ± 0.2 s  (range: 9.8 - 10.2 s)
Optimized:  7.0 s ± 0.2 s  (range: 6.8 - 7.2 s)

No overlap: Difference is statistically significant

---

System Preparation

Recommended Steps

1. Connect to Power:

# Avoid battery-saving throttling
# Ensure consistent CPU performance

2. Close Background Apps:

# macOS: Quit unnecessary apps
# Windows: Close background processes
# Linux: Stop unnecessary services

3. Disable Swapping (Temporarily):

# Linux
sudo swapoff -a
# Remember to re-enable: sudo swapon -a

4. Set CPU Governor (Linux):

# Set to performance mode
echo performance | sudo tee /sys/devices/system/cpu/cpu*/cpufreq/scaling_governor

# After benchmarking, restore:
echo powersave | sudo tee /sys/devices/system/cpu/cpu*/cpufreq/scaling_governor

5. Clear Caches:

# Clear UI5 cache
rm -rf ~/.ui5/

# Clear npm cache
npm cache clean --force

6. Avoid User Interaction:

# Don't use computer during benchmarking
# Mouse/keyboard activity can affect results

---

Best Practices

1. Use Warmup

✅ Always warm up:

hyperfine --warmup 3 'ui5 build'

❌ Skip warmup:

hyperfine 'ui5 build'  # First run may be slower!

---

2. Ensure Clean State

✅ Use preparation:

hyperfine --prepare 'rm -rf dist' 'ui5 build'

❌ Incremental builds:

hyperfine 'ui5 build'  # May reuse cached artifacts

---

3. Multiple Runs

✅ Sufficient runs:

hyperfine --runs 10 'ui5 build'  # Good statistical base

❌ Single run:

hyperfine --runs 1 'ui5 build'  # No statistical validity

---

4. Export Results

✅ Save for comparison:

hyperfine --export-json results.json 'ui5 build'
hyperfine --export-markdown results.md 'ui5 build'

Benefits: Historical tracking, charts, reports

---

5. Test Realistic Scenarios

✅ Real project:

cd real-production-app
hyperfine 'ui5 build --all'

❌ Minimal project:

cd hello-world
hyperfine 'ui5 build'  # Not representative

---

Example Workflows

Workflow 1: Measure Build Performance

#!/bin/bash
# benchmark-build.sh

# Prepare
cd my-ui5-app
rm -rf dist node_modules
npm install

# Baseline measurement
hyperfine \
  --warmup 3 \
  --runs 10 \
  --export-json baseline.json \
  --export-markdown baseline.md \
  --prepare 'rm -rf dist' \
  'ui5 build --all'

echo "Results saved to baseline.json and baseline.md"

---

Workflow 2: Compare Optimization

#!/bin/bash
# compare-optimization.sh

cd my-ui5-app

# Test baseline
echo "Testing baseline..."
hyperfine \
  --warmup 2 \
  --prepare 'rm -rf dist' \
  --command-name "standard" \
  'ui5 build --all' \
  > comparison.txt

# Test without minification
echo "Testing without minification..."
hyperfine \
  --warmup 2 \
  --prepare 'rm -rf dist' \
  --command-name "no-minify" \
  'ui5 build --all --exclude-task minify' \
  >> comparison.txt

# Test without source maps
echo "Testing without source maps..."
hyperfine \
  --warmup 2 \
  --prepare 'rm -rf dist' \
  --command-name "no-sourcemaps" \
  'ui5 build --all --exclude-task generateResourcesJson' \
  >> comparison.txt

cat comparison.txt

---

Workflow 3: Version Comparison

#!/bin/bash
# compare-versions.sh

PROJECT_DIR="my-ui5-app"
cd $PROJECT_DIR

# Install v3
npm install --save-dev @ui5/cli@^3
hyperfine \
  --warmup 2 \
  --prepare 'rm -rf dist' \
  --export-json v3.json \
  'npx ui5 build --all'

# Install v4
npm install --save-dev @ui5/cli@^4
hyperfine \
  --warmup 2 \
  --prepare 'rm -rf dist' \
  --export-json v4.json \
  'npx ui5 build --all'

# Compare
hyperfine \
  --warmup 2 \
  --prepare 'rm -rf dist' \
  'npm install --save-dev @ui5/cli@^3 && npx ui5 build --all' \
  'npm install --save-dev @ui5/cli@^4 && npx ui5 build --all'

---

Workflow 4: Dependency Impact

#!/bin/bash
# measure-dependency-impact.sh

cd my-ui5-app

# Without dependencies
hyperfine \
  --warmup 2 \
  --prepare 'rm -rf dist' \
  --command-name "app-only" \
  'ui5 build'

# With all dependencies
hyperfine \
  --warmup 2 \
  --prepare 'rm -rf dist' \
  --command-name "with-deps" \
  'ui5 build --all'

# With specific dependency
hyperfine \
  --warmup 2 \
  --prepare 'rm -rf dist' \
  --command-name "with-lib" \
  'ui5 build --include-dependency my.reuse.library'

---

Interpreting Results

Good Performance

Benchmark 1: ui5 build --all
  Time (mean ± σ):      5.234 s ±  0.056 s
  Range (min … max):    5.142 s …  5.312 s

Indicators:

• ✅ Low σ (< 5% of mean)
• ✅ Narrow range
• ✅ Consistent times

---

Performance Regression

Before: 5.0 s ± 0.1 s
After:  7.0 s ± 0.2 s

Regression: +40% slower

Action: Investigate code changes causing slowdown

---

Performance Improvement

Before: 10.0 s ± 0.2 s
After:   7.0 s ± 0.1 s

Improvement: -30% faster (1.43x speedup)

Result: Optimization successful!

---

Advanced Usage

Custom Output Format

# Markdown table
hyperfine --export-markdown results.md 'ui5 build'

# JSON for processing
hyperfine --export-json results.json 'ui5 build'

# CSV for spreadsheets
hyperfine --export-csv results.csv 'ui5 build'

---

Shell Functions

# Benchmark function
bench() {
    hyperfine --warmup 3 --prepare 'rm -rf dist' "$@"
}

# Usage
bench 'ui5 build --all'

---

Profiling with --show-output

# See command output
hyperfine --show-output 'ui5 build --all'

Use Case: Debug why benchmark is slow

---

Troubleshooting

Issue: High Variation

Symptom: σ > 10% of mean

Solutions: 1. Increase warmup runs 2. Close background apps 3. Connect to power 4. Run more iterations

---

Issue: Slow First Run

Symptom: First run much slower than subsequent

Solution: Use --warmup to skip first runs

---

Issue: Inconsistent Results

Symptom: Results vary between sessions

Solutions: 1. Clear caches before benchmarking 2. Reboot system 3. Check for background processes 4. Ensure consistent CPU governor

---

Additional Resources

• hyperfine GitHub: https://github.com/sharkdp/hyperfine
• UI5 CLI Performance: https://ui5.github.io/cli/stable/pages/Benchmarking/
• UI5 Build Options: https://ui5.github.io/cli/stable/pages/CLI/#ui5-build

---

Last Updated: 2025-11-21 Official Docs: https://ui5.github.io/cli/stable/pages/Benchmarking/

UI5 Build Process Complete Reference

Official Documentation: https://ui5.github.io/cli/stable/pages/Builder/

This reference provides comprehensive details about the UI5 build process, tasks, optimization, and bundling.

Table of Contents

1. Overview 2. Build Types 3. Standard Build Tasks 4. Minification Process 5. Source Maps 6. Bundle Generation 7. Legacy Bundle Tooling (LBT) 8. Build Optimization 9. Supported Locales Generation 10. Custom Processors

---

Overview

The UI5 Builder module orchestrates the build process for UI5 projects by defining a series of build steps (tasks) to execute. Different task sequences run based on project type (application, library, or theme-library).

Core Concept: "The UI5 Builder takes care of building your project by defining a series of build steps to execute; these are also called 'tasks.'"

Architecture:

• Tasks: Specific build steps (collect resources, apply modifications)
• Processors: Logic that modifies resources
• Workflows: Task sequences per project type

---

Build Types

Standard Build

Default execution with predefined tasks for each project type.

Command:

ui5 build
ui5 build --all                    # Include all dependencies

Tasks Executed:

• All standard tasks for project type
• Component/library preload generation
• Minification
• Theme building
• Version info generation

Output: ./dist/ directory (default)

---

Self-Contained Build

Creates standalone bundle with embedded UI5 framework.

Command:

ui5 build self-contained --all

What Happens: 1. Activates generateStandaloneAppBundle task 2. Activates transformBootstrapHtml task 3. Disables component preload generation 4. Disables library preload generation 5. Creates single bundle with all resources

Enabled Tasks:

• generateStandaloneAppBundle - Bundles app + framework
• transformBootstrapHtml - Updates bootstrap script tag

index.html Transformation:

Before:

<script id="sap-ui-bootstrap"
    src="https://ui5.sap.com/resources/sap-ui-core.js"
    data-sap-ui-libs="sap.m">
</script>

After:

<script id="sap-ui-bootstrap"
    src="Component-preload.js">
</script>

Use Case: Offline applications, embedded scenarios

---

JSDoc Build

Specialized mode for documentation generation.

Command:

ui5 build jsdoc

What Happens:

• Disables most standard tasks
• Enables JSDoc generation tasks
• Processes JavaScript for API documentation

Enabled Tasks:

• JSDoc generation
• API documentation build

Output: JSDoc HTML files in ./dist/

Requires: JSDoc must be installed and available

---

Custom Bundling

Activated when project defines bundle configuration.

Configuration:

builder:
  bundles:
    - bundleDefinition:
        name: "custom-bundle.js"
        sections:
          - mode: preload
            filters: ["my/app/**/*.js"]

What Happens:

• Enables generateBundle task
• Creates custom resource bundles
• Applies bundle optimizations

See: Bundle Generation section below

---

Standard Build Tasks

Tasks execute in specific order. Here's the complete standard task sequence:

Application Tasks (Execution Order)

Library Tasks (Execution Order)

Theme Library Tasks (Execution Order)

Common Tasks (All Project Types)

generateVersionInfo: Creates sap-ui-version.json with version metadata

---

Minification Process

The minify task compresses JavaScript resources while preserving original sources as debug variants.

How It Works

For Each JavaScript File: 1. Read source file (e.g., Module.js) 2. Minify using Terser 3. Create debug variant with -dbg suffix (Module-dbg.js) 4. Generate source map (Module.js.map) 5. Write all three files

Example:

Input:  Controller.js (10 KB, formatted)
Output: Controller.js (3 KB, minified)
        Controller-dbg.js (10 KB, original)
        Controller.js.map (source map)

Debug Variants

Purpose: Preserve original source for debugging

Naming Convention:

Module.js       → minified version
Module-dbg.js   → debug variant (original source)

Usage in Browser:

// Development: Load debug variant
sap.ui.require(["my/app/Module"]);  // Loads Module-dbg.js

// Production: Load minified
sap.ui.require(["my/app/Module"]);  // Loads Module.js

UI5 Bootstrap:

<!-- Debug mode: loads -dbg variants -->
<script src="sap-ui-core.js" data-sap-ui-debug="true"></script>

Minification Configuration

Exclude Files:

builder:
  minification:
    excludes:
      - "my/app/thirdparty/**"           # Exclude directory
      - "!my/app/thirdparty/small.js"    # Exception: minify this

What Happens:

• Excluded files copied without minification
• No debug variant created
• No source map generated

---

Source Maps

Source maps enable debugging of minified code in browsers.

Automatic Generation

For Minified Files:

// Module.js (minified)
sap.ui.define([],function(){return{getValue:function(){return 42}}});
//# sourceMappingURL=Module.js.map

Source Map (Module.js.map):

{
  "version": 3,
  "sources": ["Module-dbg.js"],
  "names": ["getValue"],
  "mappings": "AAAA...",
  "file": "Module.js"
}

Browser Usage: 1. Loads minified Module.js 2. Detects source map reference 3. Loads Module.js.map 4. Maps minified code to Module-dbg.js 5. Shows original source in DevTools

Transpilation Support

For TypeScript/Babel Projects:

The minify task incorporates input source maps created during transpilation.

Workflow:

TypeScript → JavaScript + source map → Minification → Minified + combined source map

Example:

1. Module.ts (original TypeScript)
2. tsc → Module.js + Module.js.map (transpilation)
3. ui5 build → Module.js (minified) + Module.js.map (combined)

Result: Browser can debug original TypeScript source!

Warning: Tasks like replaceVersion, replaceCopyright, and replaceBuildtime modify resources before minification. They can corrupt source maps if they alter content without updating maps.

Best Practice: Configure transpilation to generate source maps, then let minify task handle them.

---

Bundle Generation

Overview

Bundling combines multiple modules into single files for faster loading.

Bundle Modes

Configuration Example

builder:
  bundles:
    - bundleDefinition:
        name: "custom-bundle.js"
        defaultFileTypes: [".js"]
        sections:
          - mode: preload
            filters:
              - "my/app/Component.js"
              - "my/app/**/*.js"
            resolve: true              # Resolve dependencies
            resolveConditional: true   # Include conditional deps
            renderer: false            # Exclude renderers
          - mode: require
            async: true                # Use async require (v4.0+)
            filters:
              - "my/app/lazy/**/*.js"
      bundleOptions:
        optimize: true                 # Minify bundle
        sourceMap: true                # Generate source map
        decorateBootstrapModule: true  # Add bootstrap decoration

Bundle Sections

Filters: Glob patterns to match resources

Options:

• resolve: true - Include all dependencies
• resolveConditional: true - Include conditional dependencies
• renderer: false - Exclude renderer modules
• async: true - Use async require (v4.0+, default)

Bundle Options

Predefine Calls (v4.0+)

Always Used: UI5 CLI v4 always uses sap.ui.predefine calls in bundles.

Removed: usePredefineCalls option removed in v4.0.

Example Bundle Output:

sap.ui.predefine("my/app/Component", ["sap/ui/core/UIComponent"], function(UIComponent) {
    return UIComponent.extend("my.app.Component", {
        // Component code
    });
});

sap.ui.predefine("my/app/controller/Main", ["sap/ui/core/mvc/Controller"], function(Controller) {
    return Controller.extend("my.app.controller.Main", {
        // Controller code
    });
});

Async Require (v4.0+)

Default Behavior: async: true uses sap.ui.require instead of deprecated sap.ui.requireSync.

Configuration:

sections:
  - mode: require
    async: true                        # Default in v4.0
    filters: ["my/app/lazy/**"]

Output:

// async: true (default)
sap.ui.require(["my/app/lazy/Module"]);

// async: false (legacy)
sap.ui.requireSync("my/app/lazy/Module");

---

Legacy Bundle Tooling (LBT)

Overview

Deprecated in Specification Version 4.0+

For projects using Specification Version below 4.0, JavaScript files requiring "top level scope" are packaged as strings and evaluated using eval at runtime.

What is Top Level Scope?

Code with variables outside module definition:

// This requires "top level scope"
var globalVar = "something";

sap.ui.define([], function() {
    // Uses globalVar from top level
    console.log(globalVar);
});

LBT Bundling (Spec < 4.0)

String Wrapping:

// Module bundled as string
jQuery.sap.registerPreloadedModules({
    "name": "my/app/Component-preload",
    "modules": {
        "my/app/ProblematicModule.js":
            "var globalVar='something';sap.ui.define([],function(){console.log(globalVar);});"
    }
});

// Evaluated at runtime using eval()

Security & CSP Issues

Problem: eval() violates Content Security Policy (CSP)

Impact: Blocked by CSP in production

Specification 4.0+ Behavior

Breaking Change: Bundling as strings terminated.

New Behavior:

• Modules requiring top level scope cannot be bundled
• Modules omitted from bundles with error logging
• Build continues but bundle incomplete

Error Message:

WARN: Skipping module my/app/ProblematicModule.js - requires top level scope

Migration

Fix Code:

// Before (top level scope)
var globalVar = "something";
sap.ui.define([], function() {
    console.log(globalVar);
});

// After (module scope)
sap.ui.define([], function() {
    var localVar = "something";
    console.log(localVar);
});

Or Exclude from Bundle:

builder:
  componentPreload:
    excludes:
      - "my/app/ProblematicModule.js"

---

Build Optimization

Component Preload

Purpose: Bundle all Component resources for faster loading.

Configuration:

builder:
  componentPreload:
    namespaces:
      - "my/app"
      - "my/app/reuse"
    excludes:
      - "my/app/thirdparty/**"
      - "my/app/test/**"

Output: Component-preload.js in component directory

Content:

• Component.js
• All controllers
• All views (XML, JSON, HTML)
• All fragments
• Manifest.json
• i18n files

Excludes:

• Test files
• Third-party libraries
• Files matching exclude patterns

---

Library Preload

Purpose: Bundle all library resources.

Configuration:

builder:
  libraryPreload:
    excludes:
      - "my/lib/thirdparty/**"

Output: library-preload.js in library directory

Content:

• All library modules
• library.js
• Manifest.json (if exists)

---

Flex Changes Bundle

Purpose: Bundle UI flexibility changes.

Task: generateFlexChangesBundle

What It Bundles:

• SAPUI5 Flexibility changes
• UI Adaptation layer modifications
• Variant management data

Output: changes/changes-bundle.json

Automatic: No configuration needed

---

Theme Building

Purpose: Compile LESS to CSS.

Task: buildThemes

Process: 1. Find all .less files in themes/ directories 2. Compile LESS to CSS 3. Resolve theme parameters 4. Apply CSS optimizations 5. Write CSS files

Configuration:

# No configuration typically needed - automatic

Example:

Input:  src/my/lib/themes/base/library.less
Output: dist/resources/my/lib/themes/base/library.css

CSS Variables (experimental):

ui5 build --experimental-css-variables

---

Supported Locales Generation

The enhanceManifest task automatically populates supportedLocales in manifest.json.

How It Works

1. Scans project for .properties files 2. Detects locale variants (e.g., i18n_de.properties) 3. Adds supportedLocales array to manifest

Requirements

• Manifest version 1.21.0+
• Resource bundles within project namespace
• Properties files follow naming convention

Example

Files:

i18n/i18n.properties
i18n/i18n_de.properties
i18n/i18n_fr.properties
i18n/i18n_es.properties

Original manifest.json:

{
  "_version": "1.21.0",
  "sap.app": {
    "i18n": "i18n/i18n.properties"
  }
}

Enhanced manifest.json:

{
  "_version": "1.21.0",
  "sap.app": {
    "i18n": {
      "bundleUrl": "i18n/i18n.properties",
      "supportedLocales": ["de", "fr", "es", ""]
    }
  }
}

Troubleshooting

Issue: Build fails with "TypeError: invalid input"

Cause: Manifest _version incompatible with UI5 framework version.

Solution: For UI5 1.71, use manifest version ≤ 1.17.0 or update to match framework.

---

Custom Processors

Overview

Processors handle actual modification logic on supplied resources. Multiple tasks can use the same processor with different configurations.

Generic Processors

String Replacer:

• Used by replaceCopyright, replaceVersion, replaceBuildtime
• Configurable patterns and replacements

Minifier:

• Used by minify task
• Based on Terser
• Generates debug variants and source maps

Bundler:

• Used by bundle generation tasks
• Supports multiple bundle modes

Custom Processor Development

Not Recommended: Use custom tasks instead of custom processors.

Reason: Custom tasks provide simpler API and better integration.

---

Task Control

Excluding Tasks

# Exclude specific tasks
ui5 build --exclude-task minify,buildThemes

# Exclude all tasks
ui5 build --exclude-task=*

Including Tasks

# Include previously excluded tasks
ui5 build --exclude-task=* --include-task minify,generateComponentPreload

Use Cases

Fast Build (no minification):

ui5 build --exclude-task minify

Component Preload Only:

ui5 build --exclude-task=* --include-task generateComponentPreload

Documentation Build:

ui5 build jsdoc

---

Build Performance

Build Manifest

Cache build metadata for reuse:

ui5 build --create-build-manifest

Creates: .ui5/build-manifest.json with checksums

Benefit: Faster incremental builds

Dependency Building

Automatic in v3.0+: If any build task requires dependency resources, dependencies are built upfront.

Impact: Slower initial build, ensures correctness

Optimization Tips

1. Exclude unnecessary dependencies:

   ui5 build --exclude-dependency sap.ui.documentation

2. Use task control for faster dev builds:

   ui5 build --exclude-task minify

3. Enable build manifest for incremental builds:

   ui5 build --create-build-manifest

4. Parallelize builds in CI/CD

---

Best Practices

1. Use standard build for development (with task exclusions) 2. Use full build for production (ui5 build --all) 3. Always clean destination for production: --clean-dest 4. Enable source maps for debugging minified code 5. Exclude third-party from minification and bundling 6. Test self-contained builds for offline scenarios 7. Monitor build times with --perf flag 8. Use build manifest for faster incremental builds

---

Troubleshooting

Build Fails with "Module requires top level scope"

Solution: Fix code to avoid top level variables or exclude from bundle

Source Maps Not Working

Solution: Ensure transpilation generates source maps, avoid code modification tasks before minification

Slow Build Times

Solution: Exclude unnecessary dependencies, use task control, enable build manifest

Missing Resources in Output

Solution: Check builder.resources.excludes, verify resource paths

---

Last Updated: 2025-11-21 Official Docs: https://ui5.github.io/cli/stable/pages/Builder/

UI5 CLI Commands Complete Reference

Official Documentation: https://ui5.github.io/cli/stable/pages/CLI/

This reference provides comprehensive details for all UI5 CLI commands, options, and usage patterns.

Table of Contents

1. Installation & Requirements 2. Global Command Options 3. Core Commands 4. Development Commands 5. Build Commands 6. Configuration Commands 7. Utility Commands 8. Command Precedence

---

Installation & Requirements

System Requirements

• Node.js: v20.11.0+ or v22.0.0+ (v21 NOT supported)
• npm: v8.0.0 or higher

Installation Methods

Global Installation (recommended for most users):

npm install --global @ui5/cli

Local Project Installation (recommended for teams):

npm install --save-dev @ui5/cli

Verification:

ui5 --help
ui5 --version

Installation Precedence

When both global and local installations exist, the local version takes precedence automatically.

Override to use global:

UI5_CLI_NO_LOCAL=X ui5 serve

---

Global Command Options

These options work with ALL ui5 commands:

ui5 <command> [options]

Environment Variable Alternative:

UI5_LOG_LVL=verbose ui5 build

---

Core Commands

ui5 init

Initialize UI5 CLI configuration for a project.

Usage:

ui5 init

What it does:

• Creates ui5.yaml configuration file
• Detects project type (application/library)
• Sets up basic project metadata

Example:

cd my-project
ui5 init
# Creates ui5.yaml with detected configuration

---

ui5 use

Configure framework name and version.

Usage:

ui5 use <framework-info>

Framework-info format: [name][@version]

Framework names (case-insensitive):

• sapui5
• openui5

Version formats:

• latest - Latest stable version
• 1.120.0 - Specific version
• 1.120 - Latest patch of 1.120.x
• ^1.120.0 - Semantic version range
• snapshot - Latest snapshot version
• snapshot-1.120.0 - Specific snapshot version

Examples:

# SAPUI5
ui5 use sapui5@latest
ui5 use sapui5@1.120.0
ui5 use sapui5@^1.120.0
ui5 use sapui5                    # Uses latest

# OpenUI5
ui5 use openui5@latest
ui5 use openui5@1.120
ui5 use openui5

# Just version (keeps current framework)
ui5 use latest
ui5 use 1.120.0

---

ui5 add

Add framework libraries to project configuration.

Usage:

ui5 add [--development] [--optional] <framework-libraries..>

Options:

Examples:

# Add standard libraries
ui5 add sap.ui.core sap.m sap.ui.table

# Add development library
ui5 add --development sap.ui.support

# Add optional theme
ui5 add --optional themelib_sap_fiori_3

# Combined
ui5 add sap.ui.core sap.m -D sap.ui.qunit -O themelib_sap_belize

Common Libraries:

• sap.ui.core - Core framework
• sap.m - Mobile controls
• sap.ui.table - Table controls
• sap.ui.comp - Composite controls (SAPUI5 only)
• sap.ushell - Fiori Launchpad (SAPUI5 only)
• themelib_sap_fiori_3 - Fiori 3 theme
• themelib_sap_horizon - Horizon theme

---

ui5 remove

Remove framework libraries from project configuration.

Usage:

ui5 remove <framework-libraries..>

Examples:

ui5 remove sap.ui.table
ui5 remove sap.ui.comp sap.ushell

---

Development Commands

ui5 serve

Start local development web server.

Usage:

ui5 serve [options]

Options:

Standard Options: Also accepts all global options

Examples:

# Basic development server
ui5 serve

# Custom port
ui5 serve --port 1337

# Open browser automatically
ui5 serve --open index.html

# Enable HTTP/2 with HTTPS
ui5 serve --h2

# Combined options
ui5 serve --port 3000 --open test/integration/opaTests.qunit.html --h2

# Accept remote connections (useful for testing on mobile devices)
ui5 serve --accept-remote-connections

# Enable CSP policies for testing
ui5 serve --sap-csp-policies --serve-csp-reports

# Verbose logging for debugging
ui5 serve --verbose

Server URLs:

• HTTP: http://localhost:8080 (or custom port)
• HTTPS: https://localhost:8443 (when using --h2)

SSL Certificates: When using --h2, UI5 CLI automatically generates self-signed SSL certificates stored in ~/.ui5/server/. You may need to trust these certificates in your browser.

---

ui5 tree

Display project dependency tree.

Usage:

ui5 tree [options]

Options:

Examples:

# Show full dependency tree
ui5 tree

# Show flat list of all dependencies
ui5 tree --flat

# Limit to 2 levels deep
ui5 tree --level 2

# Flat list with custom workspace
ui5 tree --flat --workspace extended

Sample Output:

├─ my.application.name
│  ├─ sap.ui.core (OpenUI5 Runtime 1.120.0)
│  ├─ sap.m (OpenUI5 Runtime 1.120.0)
│  └─ my.reuse.library
│     ├─ sap.ui.core (OpenUI5 Runtime 1.120.0)
│     └─ sap.ui.layout (OpenUI5 Runtime 1.120.0)

---

Build Commands

ui5 build

Build project and create optimized bundles.

Usage:

ui5 build [child-command] [options]

Child Commands:

Dependency Options:

Output Options:

Build Options:

Task Control:

Standard Options: Also accepts all global options

Examples:

# Standard build (no dependencies)
ui5 build

# Build with all dependencies
ui5 build --all

# Build with clean destination
ui5 build --clean-dest --all

# Build to custom directory
ui5 build --dest ./build --all

# Build only specific dependencies
ui5 build --include-dependency my.reuse.library,another.library

# Build excluding certain dependencies
ui5 build --exclude-dependency sap.ui.documentation

# Build with wildcard dependency inclusion
ui5 build --include-dependency "my.company.*"

# Self-contained build (standalone bundle)
ui5 build self-contained --all

# JSDoc generation
ui5 build jsdoc

# Exclude all tasks except specific ones
ui5 build --exclude-task=* --include-task=minify,generateComponentPreload

# Experimental CSS variables
ui5 build --experimental-css-variables --all

# Flat output structure
ui5 build --output-style Flat --all

# Namespace output structure
ui5 build --output-style Namespace --all

# Combined: clean build with all dependencies and verbose logging
ui5 build --clean-dest --all --verbose

Build Output Structure:

Default Style (varies by project type):

dist/
├── resources/
│   └── my/app/
│       ├── Component.js
│       ├── Component-preload.js
│       └── manifest.json
└── index.html

Flat Style:

dist/
├── Component.js
├── Component-preload.js
├── manifest.json
└── index.html

Namespace Style:

dist/
└── my/app/
    ├── Component.js
    ├── Component-preload.js
    ├── manifest.json
    └── index.html

---

Configuration Commands

ui5 config

Manage UI5 CLI configuration settings.

Usage:

ui5 config <subcommand> [key] [value]

Subcommands:

Available Configuration Keys:

Examples:

# List all settings
ui5 config list

# Get specific setting
ui5 config get ui5DataDir

# Set custom data directory
ui5 config set ui5DataDir /custom/path/.ui5

# Clear setting (revert to default)
ui5 config set ui5DataDir

Temporary Override:

UI5_DATA_DIR=/custom/path/.ui5 ui5 build

---

Utility Commands

ui5 versions

Display all UI5 CLI module versions currently in use.

Usage:

ui5 versions

Sample Output:

@ui5/cli: 4.0.0
@ui5/builder: 4.0.0
@ui5/server: 4.0.0
@ui5/project: 4.0.0
@ui5/fs: 4.0.0
@ui5/logger: 4.0.0

Use Case: Verify installed versions when reporting issues or ensuring compatibility.

---

Command Precedence

Local vs Global CLI

When both installations exist: 1. Local installation (project's node_modules/.bin/ui5) takes precedence by default 2. Global installation (/usr/local/bin/ui5 or similar) is used as fallback

Force Global Usage:

UI5_CLI_NO_LOCAL=X ui5 <command>

Configuration File Resolution

1. --config <path> option (highest priority) 2. ui5.yaml in current directory 3. ui5.yaml in parent directories (walks up tree) 4. Error if no configuration found

Workspace Resolution

1. --workspace <name> option 2. Workspace named "default" in ui5-workspace.yaml 3. No workspace (standard dependency resolution)

---

Exit Codes

---

Best Practices

1. Use local installation for project consistency 2. Commit package.json to ensure team uses same version 3. Use `--all` for production builds to include dependencies 4. Use `--clean-dest` for production builds to avoid stale files 5. Use `--verbose` when debugging build issues 6. Use workspaces for monorepo setups instead of npm linking 7. Pin framework versions in production (avoid latest) 8. Use `ui5 serve` for development, not ui5 build 9. Test with `--h2` to simulate HTTP/2 production environment 10. Use `ui5 tree` to verify dependency resolution

---

Last Updated: 2025-11-21 (UI5 CLI v4.0.0) Official Docs: https://ui5.github.io/cli/stable/pages/CLI/

UI5 Code Analysis Complete Reference

Official Documentation: https://ui5.github.io/cli/stable/pages/CodeAnalysis/

This reference provides comprehensive details about UI5 CLI code analysis features, dependency analyzers, and JSDoc generation.

Table of Contents

1. Overview 2. JSModule Analyzer 3. Component Analyzer 4. XML Template Analyzer 5. Smart Template Analyzer 6. XML Composite Analyzer 7. library.js Analyzer 8. JSDoc Generation 9. Dependency Types

---

Overview

The UI5 CLI performs static code analysis during the build process to extract dependency information. This enables proper resource ordering, bundling optimization, and build optimization.

Purpose:

• Identify module dependencies
• Determine load order
• Optimize bundle generation
• Generate API documentation
• Enable tree shaking (future)

When It Runs: During build process, before bundling and minification

---

JSModule Analyzer

Overview

The JSModule Analyzer examines JavaScript files by parsing their Abstract Syntax Tree (AST) to identify dependencies.

Detection Methods

Supported APIs:

• sap.ui.define - Standard UI5 module definition
• sap.ui.require - Async module loading
• Deprecated APIs:
• jQuery.sap.declare - Legacy module declaration
• jQuery.sap.require - Legacy sync loading
• sap.ui.requireSync - Deprecated sync loading
• Preload APIs:
• sap.ui.preload - Preload module definitions
• sap.ui.require.preload - Preload for async require

Dependency Classification

Eager Dependencies

Definition: Dependencies unconditionally executed at module load time.

Example:

sap.ui.define([
    "sap/ui/core/mvc/Controller",    // EAGER
    "sap/m/MessageBox"                // EAGER
], function(Controller, MessageBox) {
    // Module always needs both dependencies
    return Controller.extend("my.Controller", {
        // ...
    });
});

Characteristics:

• Always loaded
• Required for module execution
• Included in preload bundles by default

---

Conditional Dependencies

Definition: Dependencies executed only under certain conditions.

Example:

sap.ui.define([
    "sap/ui/core/mvc/Controller"
], function(Controller) {
    return Controller.extend("my.Controller", {
        onPress: function() {
            if (this.needsDialog) {
                // CONDITIONAL - only loaded if needsDialog is true
                sap.ui.require(["sap/m/Dialog"], function(Dialog) {
                    var dialog = new Dialog();
                    dialog.open();
                });
            }
        }
    });
});

Characteristics:

• Loaded only when condition met
• Not included in preload by default (configurable)
• Improves initial load time

Flow Control Statements Creating Conditions:

• if / else
• switch / case
• try / catch
• while / for loops
• Function calls (may not execute)

Analysis Example

Input (Controller.js):

sap.ui.define([
    "sap/ui/core/mvc/Controller",           // Eager
    "sap/ui/model/json/JSONModel",          // Eager
    "sap/m/MessageToast"                    // Eager
], function(Controller, JSONModel, MessageToast) {
    "use strict";

    return Controller.extend("my.app.controller.Main", {
        onInit: function() {
            var model = new JSONModel();    // Uses eager dependency
            this.getView().setModel(model);
        },

        onShowDetails: function() {
            // Conditional dependency
            sap.ui.require([
                "sap/m/Dialog",
                "sap/m/Button"
            ], function(Dialog, Button) {
                var dialog = new Dialog({
                    title: "Details",
                    buttons: [
                        new Button({text: "Close"})
                    ]
                });
                dialog.open();
            });
        },

        onError: function(error) {
            MessageToast.show(error);       // Uses eager dependency
        }
    });
});

Analysis Result:

Eager Dependencies:
- sap/ui/core/mvc/Controller
- sap/ui/model/json/JSONModel
- sap/m/MessageToast

Conditional Dependencies:
- sap/m/Dialog
- sap/m/Button

Bundle Configuration Impact

Default Behavior (resolve: true):

builder:
  componentPreload:
    namespaces:
      - "my/app"

Includes: Eager dependencies only

With Conditional Resolution:

builder:
  componentPreload:
    namespaces:
      - "my/app"
    resolveConditional: true            # Include conditional deps

Includes: Eager + conditional dependencies

---

Component Analyzer

Overview

The Component Analyzer examines Component.js files and their associated manifest.json to extract dependencies from the sap.ui5 section.

Analyzed Sections

1. Library Dependencies

manifest.json:

{
  "sap.ui5": {
    "dependencies": {
      "libs": {
        "sap.ui.core": {},
        "sap.m": {},
        "sap.ui.table": {
          "minVersion": "1.120.0"
        }
      }
    }
  }
}

Extracted Dependencies:

• sap/ui/core/library
• sap/m/library
• sap/ui/table/library

---

2. Component Dependencies

manifest.json:

{
  "sap.ui5": {
    "dependencies": {
      "components": {
        "my.reuse.component": {
          "minVersion": "1.0.0"
        }
      }
    }
  }
}

Extracted Dependencies:

• my/reuse/component/Component

---

3. Models

manifest.json:

{
  "sap.ui5": {
    "models": {
      "i18n": {
        "type": "sap.ui.model.resource.ResourceModel",
        "settings": {
          "bundleName": "my.app.i18n.i18n"
        }
      },
      "": {
        "type": "sap.ui.model.odata.v2.ODataModel",
        "settings": {
          "serviceUrl": "/sap/opu/odata/sap/SERVICE"
        }
      }
    }
  }
}

Extracted Dependencies:

• sap/ui/model/resource/ResourceModel (from i18n model type)
• sap/ui/model/odata/v2/ODataModel (from default model type)

---

4. Routing Configuration

manifest.json:

{
  "sap.ui5": {
    "routing": {
      "config": {
        "viewType": "XML",
        "viewPath": "my.app.view",
        "controlId": "app",
        "controlAggregation": "pages"
      },
      "routes": [
        {
          "pattern": "",
          "name": "main",
          "target": "main"
        },
        {
          "pattern": "detail/{id}",
          "name": "detail",
          "target": "detail"
        }
      ],
      "targets": {
        "main": {
          "viewName": "Main"
        },
        "detail": {
          "viewName": "Detail"
        }
      }
    }
  }
}

Extracted Dependencies:

• my/app/view/Main.view.xml (from main target)
• my/app/view/Detail.view.xml (from detail target)

---

XML Template Analyzer

Overview

Parses XMLView and XMLFragment files to identify controls, resource bundles, and embedded fragments.

Detection Capabilities

1. Control Dependencies

XMLView (Main.view.xml):

<mvc:View
    controllerName="my.app.controller.Main"
    xmlns:mvc="sap.ui.core.mvc"
    xmlns="sap.m"
    xmlns:layout="sap.ui.layout">

    <Page title="{i18n>title}">
        <layout:VerticalLayout>
            <Button text="Click Me" press=".onPress"/>
            <List items="{/items}">
                <StandardListItem title="{title}"/>
            </List>
        </layout:VerticalLayout>
    </Page>
</mvc:View>

Extracted Dependencies:

• sap/ui/core/mvc/View
• sap/m/Page
• sap/m/Button
• sap/m/List
• sap/m/StandardListItem
• sap/ui/layout/VerticalLayout

---

2. Fragment Dependencies

XMLView with Fragment:

<mvc:View xmlns:mvc="sap.ui.core.mvc" xmlns:core="sap.ui.core" xmlns="sap.m">
    <Page>
        <core:Fragment fragmentName="my.app.view.fragments.Dialog" type="XML"/>
    </Page>
</mvc:View>

Extracted Dependencies:

• All control dependencies from the view
• my/app/view/fragments/Dialog.fragment.xml (embedded fragment)

---

3. Resource Bundle References

XMLView:

<mvc:View xmlns:mvc="sap.ui.core.mvc" xmlns="sap.m">
    <Page title="{i18n>title}">
        <Text text="{i18n>description}"/>
    </Page>
</mvc:View>

Analysis: Detects usage of resource bundle model (typically i18n)

Note: Resource bundle path resolved from manifest.json or Component.js

---

Smart Template Analyzer

Overview

Evaluates sap.ui.generic.app sections in manifest.json for SAP Fiori Elements / Smart Template configurations.

Analyzed Sections

manifest.json:

{
  "sap.ui.generic.app": {
    "pages": [
      {
        "entitySet": "Products",
        "component": {
          "name": "sap.suite.ui.generic.template.ListReport"
        },
        "pages": [
          {
            "entitySet": "Products",
            "component": {
              "name": "sap.suite.ui.generic.template.ObjectPage"
            }
          }
        ]
      }
    ]
  }
}

Extracted Dependencies:

• sap/suite/ui/generic/template/ListReport/Component
• sap/suite/ui/generic/template/ObjectPage/Component

Use Case: Fiori Elements applications using Smart Templates

---

XML Composite Analyzer

Overview

Handles deprecated XMLComposite control declarations.

Note: XMLComposite is deprecated. Use fragments or custom controls instead.

Example

Composite Control:

<core:FragmentDefinition
    xmlns="sap.m"
    xmlns:core="sap.ui.core">

    <VBox>
        <Text text="{title}"/>
        <Button text="Action"/>
    </VBox>
</core:FragmentDefinition>

Extracted Dependencies:

• sap/m/VBox
• sap/m/Text
• sap/m/Button

---

library.js Analyzer

Overview

Inspects library.js files for sap/ui/core/Core#initLibrary calls, extracting metadata.

Analyzed Data

library.js:

sap.ui.define([], function() {
    "use strict";

    sap.ui.getCore().initLibrary({
        name: "my.company.library",
        version: "1.0.0",
        dependencies: [
            "sap.ui.core",
            "sap.m"
        ],
        types: [
            "my.company.library.ButtonType",
            "my.company.library.ListType"
        ],
        interfaces: [
            "my.company.library.ISelectable"
        ],
        controls: [
            "my.company.library.controls.CustomButton",
            "my.company.library.controls.CustomList"
        ],
        elements: [
            "my.company.library.elements.CustomElement"
        ]
    });

    return my.company.library;
});

Generated manifest.json

Output (library manifest):

{
  "_version": "1.9.0",
  "sap.app": {
    "id": "my.company.library",
    "type": "library",
    "title": "My Company Library",
    "description": "Custom UI5 library",
    "version": "1.0.0"
  },
  "sap.ui": {
    "technology": "UI5",
    "deviceTypes": {
      "desktop": true,
      "tablet": true,
      "phone": true
    }
  },
  "sap.ui5": {
    "dependencies": {
      "libs": {
        "sap.ui.core": {},
        "sap.m": {}
      }
    },
    "library": {
      "i18n": false,
      "css": true,
      "content": {
        "controls": [
          "my.company.library.controls.CustomButton",
          "my.company.library.controls.CustomList"
        ],
        "elements": [
          "my.company.library.elements.CustomElement"
        ],
        "types": [
          "my.company.library.ButtonType",
          "my.company.library.ListType"
        ],
        "interfaces": [
          "my.company.library.ISelectable"
        ]
      }
    }
  }
}

Placement: Generated manifest.json placed in library directory during build

---

JSDoc Generation

Overview

UI5 CLI offers enhanced JSDoc builds with UI5-specific features.

UI5-Specific JSDoc Tags

Example:

/**
 * Custom button control.
 *
 * @class
 * @extends sap.m.Button
 * @author My Company
 * @version 1.0.0
 * @public
 * @since 1.0.0
 * @experimental Since 1.0.0 - API may change
 * @ui5-restricted sap.suite, sap.ushell
 */

AST Visitor

Purpose: Detect UI5-specific extend calls for inheritance hierarchy.

Example:

sap.ui.define([
    "sap/ui/core/Control"
], function(Control) {
    return Control.extend("my.CustomControl", {
        // Control implementation
    });
});

Detection: JSDoc AST visitor identifies:

• Base class (sap/ui/core/Control)
• Extended class name (my.CustomControl)
• Inheritance relationship

API Documentation Generation

Build Command:

ui5 build jsdoc

Process: 1. Scan all JavaScript files 2. Parse JSDoc comments 3. Build inheritance hierarchy 4. Calculate complete API surface 5. Generate HTML documentation

Output:

dist/
└── test-resources/
    └── jsdoc/
        ├── index.html
        ├── symbols/
        │   ├── my.CustomControl.html
        │   └── ...
        └── styles/

Version Utilities

Purpose: Track API changes across versions.

Features:

• Mark deprecated APIs
• Track experimental features
• Document version-specific changes
• Generate version comparison reports

---

Dependency Types

Summary

---

Best Practices

1. Use Standard APIs: Prefer sap.ui.define over deprecated APIs 2. Lazy Load: Use conditional dependencies for optional features 3. Document Dependencies: Add JSDoc for clarity 4. Test Bundles: Verify all dependencies included in preload 5. Enable Conditional Resolution: For complete bundles 6. Generate JSDoc: Keep API documentation up-to-date 7. Analyze Build: Use verbose logging to see dependency resolution

---

Troubleshooting

Missing Dependencies in Bundle

Check: 1. Dependency declared in sap.ui.define? 2. Conditional dependency? (need resolveConditional: true) 3. Resource excluded? (check excludes configuration)

Circular Dependencies

Symptom: Module loading fails at runtime

Solution: 1. Analyze dependency graph: ui5 tree 2. Refactor to remove circular references 3. Use lazy loading for one direction

JSDoc Build Fails

Error: Non-zero exit code from JSDoc

Solution: 1. Fix JSDoc syntax errors in code 2. Ensure all referenced types exist 3. Check JSDoc configuration

---

Last Updated: 2025-11-21 Official Docs: https://ui5.github.io/cli/stable/pages/CodeAnalysis/

UI5 CLI Configuration Complete Reference

Official Documentation: https://ui5.github.io/cli/stable/pages/Configuration/ JSON Schema: https://ui5.github.io/cli/schema/ui5.yaml.json

This reference provides comprehensive details for ui5.yaml configuration files.

Table of Contents

1. Overview 2. Core Structure 3. Specification Versions 4. Project Types 5. Metadata Configuration 6. Framework Configuration 7. Resources Configuration 8. Builder Configuration 9. Server Configuration 10. Custom Configuration 11. Extension Configuration 12. Version-Specific Features

---

Overview

Every UI5 CLI project requires a ui5.yaml configuration file in the project root. The configuration is validated against the JSON schema for correctness.

Validation: Use the official schema for IDE validation and autocompletion.

---

Core Structure

Every ui5.yaml requires these three essential elements:

specVersion: "4.0"              # Specification version (required)
type: application               # Project type (required)
metadata:
  name: my.project.name         # Project name (required)

---

Specification Versions

The specVersion determines available features and CLI compatibility.

Recommendation: Always use the latest specVersion for new projects.

Current: specVersion "4.0" (as of 2025-11-21)

---

Project Types

UI5 CLI supports four project types:

Application

Standard UI5 applications.

Path Mapping: webapp/ → / (runtime)

Configuration:

specVersion: "4.0"
type: application
metadata:
  name: my.company.app
resources:
  configuration:
    paths:
      webapp: webapp              # Default

Build Output: Creates Component-preload.js when Component.js exists.

---

Library

Reusable component libraries.

Path Mappings:

• src/ → /resources (runtime)
• test/ → /test-resources (runtime)

Configuration:

specVersion: "4.0"
type: library
metadata:
  name: my.company.library
resources:
  configuration:
    paths:
      src: src                    # Default
      test: test                  # Optional

Requirements:

• Must contain namespace directory structure (e.g., src/my/company/library/)
• Should include library.js and .library files

---

Theme Library

Specialized library for UI5 themes.

Path Mappings: Same as library (src/ → /resources, test/ → /test-resources)

Configuration:

specVersion: "4.0"
type: theme-library
metadata:
  name: my.company.themelibrary
resources:
  configuration:
    paths:
      src: src
      test: test

Resource Organization: src/my/library/themes/my_custom_theme/

Available Since: Specification Version 1.1

---

Module

Third-party resources with flexible path mapping.

Path Mappings: Custom virtual-to-physical mappings.

Configuration:

specVersion: "4.0"
type: module
metadata:
  name: thirdparty.module
resources:
  configuration:
    paths:
      /resources/my/lib/thirdparty/: lib

Characteristics:

• Resources copied without modification
• No preload generation
• Useful for non-UI5 libraries (jQuery, lodash, etc.)

---

Metadata Configuration

metadata:
  name: my.company.project               # Required
  copyright: "© ${currentYear} Company"  # Optional
  deprecated: false                      # Optional (default: false)

Name Requirements

Format Rules:

• 3-80 characters
• Lowercase alphanumeric, dashes, underscores, periods
• Must start with alphabetic character or @
• Can use npm scope format: @myorg/myproject

Examples:

# Valid
name: my.application
name: my-library
name: my_module
name: "@myorg/mylib"

# Invalid
name: MyApplication                      # Uppercase not allowed (specVersion 3.0+)
name: my                                 # Too short
name: 123project                         # Must start with letter or @

Copyright

Dynamic Placeholder: ${currentYear} automatically updates each year.

Examples:

copyright: "My Company © ${currentYear}"
copyright: "Copyright ${currentYear} SAP SE"

Deprecated

Mark project as deprecated:

deprecated: true

---

Framework Configuration

Configure OpenUI5 or SAPUI5 framework dependencies.

Basic Structure

framework:
  name: SAPUI5                    # OpenUI5 or SAPUI5 (case-insensitive)
  version: "1.120.0"              # Specific version or range
  libraries:
    - name: sap.ui.core
    - name: sap.m
    - name: sap.ui.table
      optional: true              # Optional library
    - name: sap.ui.support
      development: true           # Development-only library

Framework Names

Compatibility: SAPUI5 projects can depend on OpenUI5, but not vice versa.

Version Formats

version: "1.120.0"                # Exact version
version: "1.120"                  # Latest patch of 1.120.x
version: "^1.120.0"               # Semantic versioning range
version: "latest"                 # Latest stable
version: "snapshot"               # Latest snapshot
version: "snapshot-1.120.0"       # Specific snapshot

Library Configuration

Standard Library:

libraries:
  - name: sap.ui.core

Optional Library (included only if available):

libraries:
  - name: themelib_sap_horizon
    optional: true

Development Library (excluded from production builds):

libraries:
  - name: sap.ui.support
    development: true
  - name: sap.ui.qunit
    development: true

Common Libraries

OpenUI5 & SAPUI5:

• sap.ui.core - Core framework (always required)
• sap.m - Mobile/responsive controls
• sap.ui.layout - Layout controls
• sap.ui.table - Table controls
• sap.ui.unified - Unified controls

SAPUI5 Only:

• sap.ui.comp - Composite/smart controls
• sap.ushell - Fiori Launchpad
• sap.fe - Fiori Elements
• sap.suite.ui.commons - Suite commons

Themes:

• themelib_sap_fiori_3 - Fiori 3 theme
• themelib_sap_horizon - Horizon theme (latest)
• themelib_sap_belize - Belize theme
• themelib_sap_bluecrystal - Blue Crystal theme (legacy)

---

Resources Configuration

Configure resource paths and encoding.

Path Mapping

Application:

resources:
  configuration:
    paths:
      webapp: webapp                    # Maps to / at runtime

Library:

resources:
  configuration:
    paths:
      src: src                          # Maps to /resources at runtime
      test: test                        # Maps to /test-resources at runtime

Module:

resources:
  configuration:
    paths:
      /resources/thirdparty/lodash/: node_modules/lodash/dist

Properties File Encoding

resources:
  configuration:
    propertiesFileSourceEncoding: UTF-8       # Default for specVersion 2.0+

Encoding Options:

• UTF-8 (default for specVersion 2.0+)
• ISO-8859-1 (default for specVersion < 2.0)

Use Case: Ensure proper handling of non-ASCII characters in .properties files.

---

Builder Configuration

Configure build behavior, tasks, and optimization.

Resource Exclusions

Exclude files from build output:

builder:
  resources:
    excludes:
      - "index.html"                    # Exclude specific file
      - "/resources/my/app/test/**"     # Exclude directory
      - "**/*.test.js"                  # Exclude pattern

Glob Patterns Supported: Standard glob syntax with *, **, ?

Component Preload

Configure Component-preload.js generation:

builder:
  componentPreload:
    namespaces:
      - "my/app"                        # Include namespace
      - "my/app/reuse"                  # Include sub-namespace
    excludes:
      - "my/app/thirdparty/**"          # Exclude from preload
      - "my/app/localService/**"        # Exclude mock data

When Used: Only for applications with Component.js

Library Preload

Configure library-preload.js generation:

builder:
  libraryPreload:
    excludes:
      - "my/lib/thirdparty/"            # Exclude directory
      - "!my/lib/thirdparty/important.js"  # Exception: include this file

Negation: Prefix with ! to include despite parent exclusion

Minification

Configure JavaScript minification:

builder:
  minification:
    excludes:
      - "my/lib/thirdparty/**"          # Don't minify third-party
      - "!my/lib/thirdparty/small.js"   # Exception: minify this

What Happens:

• Module.js → minified
• Module-dbg.js → original source (debug variant)
• Module.js.map → source map generated

Cachebuster

Configure cache-busting for resources:

builder:
  cachebuster:
    signatureType: hash                 # hash or time

Signature Types:

• hash - Content-based hash (recommended)
• time - Timestamp-based

Result: Appends signature to resource URLs for cache invalidation

Custom Bundling

Define custom resource bundles:

builder:
  bundles:
    - bundleDefinition:
        name: "app-bundle.js"
        sections:
          - mode: preload
            filters:
              - "my/app/Component.js"
              - "my/app/**/*.js"
            resolve: true
            resolveConditional: true
            renderer: false
      bundleOptions:
        optimize: true
        sourceMap: true
        usePredefineCalls: true         # Deprecated in v4.0

Bundle Modes:

Bundle Options:

• optimize: true - Minify bundle (default: true in v3.0+)
• sourceMap: true - Generate source map
• decorateBootstrapModule: true - Add bootstrap decoration
• addTryCatchRestartWrapper: true - Add error handling

Custom Tasks

Integrate custom build tasks:

builder:
  customTasks:
    - name: babel-transpile
      beforeTask: replaceCopyright      # Execute before this task
      configuration:
        enabled: true
        preset: "@babel/preset-env"

    - name: optimize-images
      afterTask: minify                 # Execute after this task
      configuration:
        quality: 80

Task Ordering:

• beforeTask: <taskName> - Execute before specified task
• afterTask: <taskName> - Execute after specified task

Configuration: Passed to custom task implementation

See: references/extensibility.md for custom task development

---

Server Configuration

Configure development server behavior.

Port Configuration

server:
  settings:
    httpPort: 8080                      # HTTP port (default)
    httpsPort: 8443                     # HTTPS port (default)

CLI Override:

ui5 serve --port 3000
ui5 serve --h2 --https-port 4000

Custom Middleware

Extend server with custom middleware:

server:
  customMiddleware:
    - name: myCustomMiddleware
      mountPath: /myapp                 # Optional path
      afterMiddleware: compression      # Ordering
      configuration:
        debug: true
        apiKey: "secret"

See: references/extensibility.md for custom middleware development

---

Custom Configuration

Store custom tool configuration:

customConfiguration:
  myTool:
    key: value
    nested:
      setting: 123

Purpose: Allow third-party tools to store UI5-specific settings

Ignored by: UI5 CLI (reserved for external tools)

---

Extension Configuration

Extensions use kind: extension and are separated by ---.

Project Shim Extension

specVersion: "4.0"
type: application
metadata:
  name: my.app
---
specVersion: "4.0"
kind: extension
type: project-shim
metadata:
  name: my.app.shims
shims:
  configurations:
    lodash:                             # npm package name
      specVersion: "4.0"
      type: module
      metadata:
        name: thirdparty.lodash
      resources:
        configuration:
          paths:
            /resources/thirdparty/lodash/: dist

Custom Task Extension

---
specVersion: "4.0"
kind: extension
type: task
metadata:
  name: my-custom-task
task:
  path: lib/tasks/myTask.js

Custom Middleware Extension

---
specVersion: "4.0"
kind: extension
type: server-middleware
metadata:
  name: my-custom-middleware
middleware:
  path: lib/middleware/myMiddleware.js

See: references/extensibility.md for detailed extension development

---

Version-Specific Features

Version 4.0 (UI5 CLI v4.0.0+)

Breaking Changes:

• Removed usePredefineCalls bundle option
• Async require sections default to async: true

New Features:

• Async require section support in bundles

Migration:

# v3.x
builder:
  bundles:
    - bundleDefinition:
        name: "bundle.js"
        sections:
          - mode: require
            filters: ["my/app/**"]
      bundleOptions:
        usePredefineCalls: true         # Remove this

# v4.0
builder:
  bundles:
    - bundleDefinition:
        name: "bundle.js"
        sections:
          - mode: require
            async: true                  # Add this
            filters: ["my/app/**"]

Version 3.2 (UI5 CLI v3.11.0+)

New Features:

• depCache bundling mode for dependency caching

builder:
  bundles:
    - bundleDefinition:
        sections:
          - mode: depCache              # New mode

Version 3.1 (UI5 CLI v3.10.0+)

New Features:

• builder.resources.excludes now supported for module projects

Version 3.0 (UI5 CLI v3.0.0+)

Breaking Changes:

• metadata.name restricted to lowercase characters
• optimize defaults to true in bundle options

New Features:

• sourceMap support in bundle options

Version 2.6 (UI5 CLI v2.14.0+)

New Features:

• builder.minification.excludes for selective minification

Version 2.0 (UI5 CLI v2.0.0+)

Breaking Changes:

• Schema validation enforced
• Default properties encoding changed to UTF-8

New Features:

• SAPUI5 framework support
• Framework configuration section

---

Complete Example

specVersion: "4.0"
type: application
metadata:
  name: my.company.app
  copyright: "© ${currentYear} My Company"
  deprecated: false

framework:
  name: SAPUI5
  version: "1.120.0"
  libraries:
    - name: sap.ui.core
    - name: sap.m
    - name: sap.ui.table
    - name: sap.ui.comp
    - name: themelib_sap_horizon
      optional: true
    - name: sap.ui.qunit
      development: true

resources:
  configuration:
    paths:
      webapp: webapp
    propertiesFileSourceEncoding: UTF-8

builder:
  resources:
    excludes:
      - "index.html"
      - "/resources/my/company/app/test/**"

  componentPreload:
    namespaces:
      - "my/company/app"
    excludes:
      - "my/company/app/thirdparty/**"

  minification:
    excludes:
      - "my/company/app/thirdparty/**"

  cachebuster:
    signatureType: hash

  customTasks:
    - name: babel-transpile
      beforeTask: replaceCopyright
      configuration:
        presets: ["@babel/preset-env"]

server:
  settings:
    httpPort: 8080
    httpsPort: 8443

  customMiddleware:
    - name: api-proxy
      afterMiddleware: compression
      configuration:
        target: https://api.example.com

---

Best Practices

1. Always use latest specVersion for new projects 2. Pin framework versions for production stability 3. Mark optional libraries as optional: true 4. Mark dev libraries as development: true 5. Use hash-based cachebuster for better caching 6. Exclude test resources from production builds 7. Validate against JSON schema in IDE 8. Document custom configuration in project README 9. Use lowercase names for metadata (required in v3.0+) 10. Commit ui5.yaml to version control

---

Last Updated: 2025-11-21 (UI5 CLI v4.0.0) Official Docs: https://ui5.github.io/cli/stable/pages/Configuration/ JSON Schema: https://ui5.github.io/cli/schema/ui5.yaml.json

UI5 CLI ECMAScript Support Reference

Official Documentation: https://ui5.github.io/cli/stable/pages/ESSupport/

This reference provides complete information about ECMAScript version support, module formats, and language feature restrictions in UI5 CLI.

Table of Contents

1. Supported ECMAScript Versions 2. Module Format Requirements 3. Language Feature Restrictions 4. Build-Time Replacements 5. Best Practices 6. Migration Guide

---

Supported ECMAScript Versions

UI5 CLI supports different ECMAScript versions depending on the CLI version used.

Version Matrix

Important Note

Parsing vs Analysis: "Code up to ECMAScript 2020 can be parsed, however required code analysis might not work correctly for specific language features."

Recommendation: Use the ECMAScript version matching your UI5 CLI version for guaranteed compatibility.

---

Module Format Requirements

Critical Restriction: No ES6 Modules

UI5 CLI does NOT support JavaScript modules with `import`/`export` syntax.

Reason: UI5 CLI "only analyzes JavaScript files of type script" and cannot process ES6 module syntax.

❌ Unsupported (ES6 Modules)

// This will NOT work with UI5 CLI
import Component from './Component.js';
import { Controller } from 'sap/ui/core/mvc/Controller.js';

export default class MyController extends Controller {
    // ...
}

export function helper() {
    // ...
}

Error: Modules not recognized, dependencies not resolved, build fails.

---

✅ Supported (UI5 AMD Modules)

Use `sap.ui.define` instead:

// This works correctly with UI5 CLI
sap.ui.define([
    './Component',
    'sap/ui/core/mvc/Controller'
], function(Component, Controller) {
    'use strict';

    return Controller.extend('my.app.controller.MyController', {
        // Controller implementation
    });
});

For helper functions:

sap.ui.define([], function() {
    'use strict';

    return {
        helper: function() {
            // Helper implementation
        }
    };
});

Module Definition Patterns

Single Class/Object Export:

sap.ui.define([
    'sap/ui/core/UIComponent'
], function(UIComponent) {
    return UIComponent.extend('my.app.Component', {
        // ...
    });
});

Multiple Exports (as object):

sap.ui.define([], function() {
    return {
        formatDate: function(date) { /* ... */ },
        formatNumber: function(num) { /* ... */ },
        formatCurrency: function(amount) { /* ... */ }
    };
});

Usage:

sap.ui.define([
    'my/app/util/Formatter'
], function(Formatter) {
    Formatter.formatDate(new Date());
});

---

Language Feature Restrictions

While modern ES syntax is supported for parsing, certain features have usage restrictions that affect code analysis and bundling.

1. Template Literals with Expressions

❌ Not Allowed In

Dependency Declarations:

// FAILS - Cannot use expression in dependency path
const moduleName = "Controller";
sap.ui.define([
    `sap/ui/core/mvc/${moduleName}`  // ❌ Will not be analyzed
], function(Controller) {
    // ...
});

Smart Template Names:

// FAILS in manifest.json Smart Template configuration
{
    "component": {
        "name": `sap.suite.ui.generic.template.${templateType}`  // ❌
    }
}

Library Initialization:

// FAILS - Cannot use template literal with expression
sap.ui.getCore().initLibrary({
    name: `my.company.${libName}`  // ❌
});

✅ Allowed

Static Template Literals (no expressions):

sap.ui.define([
    `sap/ui/core/mvc/Controller`  // ✅ OK (no expression)
], function(Controller) {
    // ...
});

In Code Logic:

sap.ui.define([], function() {
    return {
        getMessage: function(name) {
            return `Hello, ${name}!`;  // ✅ OK
        }
    };
});

---

2. Spread Elements

❌ Not Allowed In

`sap.ui.define` / `sap.ui.require` Calls:

// FAILS - Spread not supported in dependency arrays
const coreDeps = ['sap/ui/core/Core', 'sap/ui/core/UIComponent'];
sap.ui.define([
    ...coreDeps,  // ❌ Will not be analyzed
    'sap/m/Button'
], function(Core, UIComponent, Button) {
    // ...
});

Smart Template Configurations:

// FAILS in manifest.json
{
    "pages": [
        ...commonPages,  // ❌
        { "entitySet": "Products" }
    ]
}

XMLComposite Declarations:

// FAILS
const props = {type: "Button", text: "Click"};
<Button {...props} />  // ❌

✅ Allowed

In Object/Array Literals (code logic):

sap.ui.define([], function() {
    return {
        mergeData: function(obj1, obj2) {
            return { ...obj1, ...obj2 };  // ✅ OK
        },
        combineArrays: function(arr1, arr2) {
            return [...arr1, ...arr2];  // ✅ OK
        }
    };
});

---

3. Object Properties (Computed/Dynamic)

❌ Not Allowed In

Module Names:

// FAILS - Dynamic module names not supported
const modules = {
    controller: 'sap/ui/core/mvc/Controller'
};
sap.ui.define([
    modules.controller  // ❌ Will not be analyzed
], function(Controller) {
    // ...
});

Library Initialization:

// FAILS
const config = {
    name: "my.library"
};
sap.ui.getCore().initLibrary(config);  // ❌ Must be literal object

✅ Allowed

In Code Logic:

sap.ui.define([], function() {
    return {
        createConfig: function(key, value) {
            return {
                [key]: value  // ✅ OK (computed property)
            };
        }
    };
});

---

4. Class Declarations

⚠️ Restriction

Don't Return Inline:

// PROBLEMATIC - JSDoc may not be associated correctly
sap.ui.define([
    'sap/ui/core/Control'
], function(Control) {
    return class extends Control {  // ⚠️ Avoid
        // ...
    };
});

✅ Recommended

Declare Separately Before Returning:

// RECOMMENDED
sap.ui.define([
    'sap/ui/core/Control'
], function(Control) {
    /**
     * My custom control.
     * @class
     * @extends sap.ui.core.Control
     */
    class MyControl extends Control {
        // ...
    }

    return MyControl;
});

Or Use Traditional Pattern:

// TRADITIONAL (always works)
sap.ui.define([
    'sap/ui/core/Control'
], function(Control) {
    /**
     * My custom control.
     * @class
     * @extends sap.ui.core.Control
     */
    return Control.extend('my.app.control.MyControl', {
        // ...
    });
});

---

5. Arrow Functions & JSDoc

⚠️ Restriction

JSDoc Placement:

// PROBLEMATIC - JSDoc not associated with arrow function
/**
 * My module
 */
sap.ui.define([], () => {  // ⚠️ JSDoc won't be recognized
    // ...
});

✅ Recommended

JSDoc Above Arrow Function:

sap.ui.define([], function() {
    return {
        /**
         * Formats a date.
         * @param {Date} date - The date to format
         * @returns {string} Formatted date
         */
        formatDate: (date) => {  // ✅ JSDoc directly above
            return date.toLocaleDateString();
        }
    };
});

---

Build-Time Replacements

Reserved Variable Names

These variable names are replaced during build and should not appear in template literal expressions:

❌ Don't Use In Template Literals

// FAILS - Will be replaced during build
const message = `Version: ${version}`;  // ❌ ${version} replaced!

✅ Use Alternatives

Option 1 - Use Different Variable Names:

const myVersion = "1.0.0";
const message = `Version: ${myVersion}`;  // ✅ OK

Option 2 - Use String Concatenation:

const message = "Version: " + version;  // ✅ OK

Option 3 - Access at Runtime:

sap.ui.define([
    'sap/ui/core/Component'
], function(Component) {
    return Component.extend('my.app.Component', {
        getVersion: function() {
            // Access version from manifest at runtime
            return this.getManifestEntry('sap.app').applicationVersion.version;
        }
    });
});

---

Best Practices

1. Module Definition

✅ Always use `sap.ui.define`:

sap.ui.define([
    'sap/ui/core/mvc/Controller'
], function(Controller) {
    'use strict';
    return Controller.extend('my.Controller', {});
});

❌ Never use ES6 imports:

import Controller from 'sap/ui/core/mvc/Controller';  // ❌

---

2. Dependencies

✅ Use static dependency arrays:

sap.ui.define([
    'sap/ui/core/Core',
    'sap/m/Button'
], function(Core, Button) {
    // ...
});

❌ Avoid dynamic dependencies:

const deps = ['sap/m/Button'];
sap.ui.define(deps, function(Button) {});  // ❌

---

3. Modern ES Features

✅ Use modern syntax in code logic:

sap.ui.define([], function() {
    return {
        // Arrow functions ✅
        map: (items) => items.map(i => i.value),

        // Destructuring ✅
        extract: ({name, value}) => ({name, value}),

        // Spread operator ✅
        merge: (a, b) => ({...a, ...b}),

        // Template literals ✅
        format: (name) => `Hello, ${name}!`,

        // Async/await ✅
        load: async function() {
            const data = await fetch('/api/data');
            return data.json();
        }
    };
});

---

4. Class Syntax

✅ Declare then return:

sap.ui.define(['sap/ui/core/Control'], function(Control) {
    class MyControl extends Control {
        constructor() {
            super();
        }
    }
    return MyControl;
});

✅ Or use traditional extend:

sap.ui.define(['sap/ui/core/Control'], function(Control) {
    return Control.extend('my.Control', {
        init: function() {
            // ...
        }
    });
});

---

Migration Guide

From ES6 Modules to UI5 AMD

Before (ES6):

import Controller from 'sap/ui/core/mvc/Controller';
import MessageToast from 'sap/m/MessageToast';

export default class Main extends Controller {
    onPress() {
        MessageToast.show("Pressed!");
    }
}

After (UI5 AMD):

sap.ui.define([
    'sap/ui/core/mvc/Controller',
    'sap/m/MessageToast'
], function(Controller, MessageToast) {
    'use strict';

    return Controller.extend('my.app.controller.Main', {
        onPress: function() {
            MessageToast.show("Pressed!");
        }
    });
});

---

Modernizing Legacy Code

Old (ES5):

sap.ui.define([], function() {
    return {
        format: function(items) {
            return items.map(function(item) {
                return item.value;
            });
        }
    };
});

Modern (ES2022):

sap.ui.define([], function() {
    return {
        format: (items) => items.map(item => item.value)
    };
});

---

Summary Table

---

Troubleshooting

Issue: Dependencies Not Resolved

Symptom: Build succeeds but modules not found at runtime

Cause: Using dynamic dependencies or template literals with expressions

Solution: Use static string literals in dependency array

---

Issue: Build Fails with Syntax Error

Symptom: "Unexpected token" during build

Cause: Using ES6 import/export syntax

Solution: Convert to sap.ui.define pattern

---

Issue: JSDoc Not Generated

Symptom: API documentation missing for module

Cause: JSDoc not associated with arrow function or inline class

Solution: Place JSDoc directly above declaration, or declare separately

---

Additional Resources

• UI5 Documentation: https://ui5.sap.com/
• sap.ui.define: https://ui5.sap.com/#/api/sap.ui/methods/sap.ui.define
• UI5 Modules: https://ui5.sap.com/#/topic/91f23a736f4d1014b6dd926db0e91070

---

Last Updated: 2025-11-21 Official Docs: https://ui5.github.io/cli/stable/pages/ESSupport/