sapui5-cli

What this skill does

# SAPUI5/OpenUI5 CLI Management Skill

## Related Skills

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

## Table of Contents
- [Overview](#overview)
- [When to Use This Skill](#when-to-use-this-skill)
- [Quick Start Workflow](#quick-start-workflow)
- [Project Types](#project-types)
- [Bundled Resources](#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

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

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

```yaml
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 developme