sapui5-cli

SAPUI5/OpenUI5 CLI 管理スキル

関連スキル

• sap-dependency-security：UI5 ツーリングのワークフローで、安全な CLI／ツールチェーンのアップグレード、ロックファイルの強化、決定論的なインストールを行う際に使用します。

目次

• 概要
• このスキルを使用する場面
• クイックスタートワークフロー
• プロジェクトの種類
• 同梱リソース

概要

このスキルでは、SAPUI5 および OpenUI5 アプリケーションとライブラリの開発、ビルド、デプロイに使用する公式コマンドラインインターフェイスである UI5 CLI（UI5 Tooling）を包括的に扱います。

現在の CLI バージョン：4.0.55（2026-05-31 に npm で確認済み） Node.js の要件：v20.11.0 以上、または v22.0.0 以上（v21 はサポートされていません） npm の要件：v8.0.0 以上

このスキルを使用する場面

次の作業が必要な場合に、このスキルを使用してください。

• UI5 プロジェクトを新規作成する、または既存のプロジェクトで CLI を利用できるようにする
• アプリケーション、ライブラリ、テーマライブラリ、モジュール用の ui5.yaml を設定する
• 最適化、バンドル、圧縮を行いながら UI5 プロジェクトをビルドする
• HTTP/2、SSL、CSP をサポートするローカル開発サーバーを実行する
• カスタムタスクやサーバーミドルウェアでビルドプロセスを拡張する
• 複数の UI5 プロジェクトを含むモノレポ／ワークスペースの設定を管理する
• 一般的な UI5 CLI エラーやビルドの問題をトラブルシューティングする
• CLI のバージョン間（v1 → v2 → v3 → v4）を移行する
• ビルドのパフォーマンスを最適化し、依存関係を分析する

クイックスタートワークフロー

新規プロジェクトのセットアップ

# 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

既存プロジェクトのセットアップ

# 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

プロジェクトの種類

UI5 CLI は、固有の設定を持つ次の 4 種類のプロジェクトをサポートしています。

1. アプリケーション

webapp ディレクトリを持つ標準的な UI5 アプリケーションです。

• 仮想パスのマッピング：webapp/ → /
• Component.js が存在する場合、Component-preload.js を生成します
• 設定テンプレートについては templates/ui5.yaml.application を参照してください

2. ライブラリ

プロジェクト間で共有するための再利用可能なコンポーネントライブラリです。

• 仮想パスのマッピング：src/ → /resources、test/ → /test-resources
• 名前空間ディレクトリ構造が必要です（例：src/my/company/library/）
• 設定テンプレートについては templates/ui5.yaml.library を参照してください

3. テーマライブラリ

ライブラリ用のテーマリソースを提供します。

• 標準ライブラリと同じ仮想パスマッピングを使用します
• リソースは名前空間ごとに整理されます（例：my/library/themes/custom_theme/）
• 詳細な設定については references/configuration.md を参照してください

4. モジュール

柔軟なパスマッピングに対応するサードパーティーリソースです。

• リソースは変更せずにコピーされます
• 仮想パスから物理パスへのマッピングをカスタマイズできます
• モジュールの設定については references/project-structures.md を参照してください

コアコマンドのリファレンス

プロジェクトの初期化

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

開発

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

ビルド

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]

設定

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

ユーティリティ

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

コマンドの全リファレンスについては、references/cli-commands.md を参照してください。

設定ファイルの構造

ui5.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

設定の全リファレンスについては、references/configuration.md を参照してください。

段階的な情報開示：詳細なリファレンス

このメインスキルファイルでは、基本的なワークフローとクイックリファレンスを紹介しています。特定のトピックの詳細については、次のリファレンスファイルを参照してください。

コアリファレンス

• references/cli-commands.md：すべてのオプションと例を含む CLI コマンドの全リファレンス
• references/configuration.md：ui5.yaml の包括的な設定ガイド（ワークスペース設定を含む）
• references/project-structures.md：ディレクトリ構造とビルド出力形式を含む、プロジェクトの種類に関する詳細情報

高度なトピック

• references/extensibility.md：完全な API ドキュメントを含む、カスタムタスク、ミドルウェア、プロジェクトシム
• references/filesystem-api.md：カスタムタスク／ミドルウェア開発向けの完全な FileSystem API
• references/build-process.md：タスク、ミニファイ、ソースマップ、バンドルを含むビルドプロセス全般
• references/server-features.md：ミドルウェアスタック、HTTP/2、SSL、CSP を含むサーバーの完全なドキュメント
• references/code-analysis.md：依存関係アナライザー、JSDoc 生成、コード分析機能
• references/es-support.md：ECMAScript のバージョンサポート、制限事項、モジュール形式の要件全般

パフォーマンスとトラブルシューティング

• references/benchmarking.md：hyperfine を使用したパフォーマンステストとベンチマーク
• references/migration-guides.md：バージョン移行ガイド全般（v1→v2→v3→v4）
• references/troubleshooting.md：正確なエラーメッセージを含む、一般的な問題、エラー、解決策

一般的なワークフロー

ワークフロー 1：新しいアプリケーションのセットアップ

使用する場面：SAPUI5/OpenUI5 アプリケーションをゼロから作成する場合。

手順：

1. npm プロジェクトを初期化します：npm init --yes
2. UI5 CLI をインストールします：npm install --save-dev @ui5/cli
3. UI5 設定を初期化します：ui5 init
4. フレームワークを選択します：ui5 use sapui5@latest（または openui5@latest）
5. 必要なライブラリを追加します：ui5 add sap.ui.core sap.m themelib_sap_fiori_3
6. アプリケーションの構成を作成します（webapp/, Component.js, manifest.json）
7. 開発サーバーを起動します：ui5 serve
8. 設定をコミットします：git add ui5.yaml package.json && git commit

ワークフロー 2：既存プロジェクトでの CLI の有効化

使用する場面：既存の UI5 プロジェクトに UI5 CLI のサポートを追加する場合。

手順：

1. プロジェクトのルートに移動します
2. ui5 init を実行して ui5.yaml を作成します
3. フレームワークを設定します：ui5 use sapui5@latest
4. ライブラリを追加します：ui5 add sap.ui.core sap.m sap.ui.table
5. 必要に応じて ui5.yaml の resources.configuration.paths を調整します
6. ui5 serve でテストします
7. ui5 build --all でビルドします

ワークフロー 3：カスタムビルドタスクの作成

使用する場面：カスタム処理でビルドプロセスを拡張する場合。

手順：

1. タスクファイルを作成します（例：lib/tasks/customTask.js）
2. Task API を使用してタスクを実装します（templates/custom-task-template.js を参照）
3. ui5.yaml または別ファイルにタスク拡張を作成します
4. builder.customTasks セクションでタスクを設定します
5. ui5 build でテストします
6. 詳細は references/extensibility.md を参照してください

ワークフロー 4：ワークスペース／モノレポのセットアップ

使用する場面：1 つのリポジトリで複数の関連 UI5 プロジェクトを管理する場合。

手順：

1. ルートプロジェクトに ui5-workspace.yaml を作成します
2. ワークスペース名と依存関係の解決方法を定義します
3. 相対パスを使ってローカルプロジェクトのディレクトリを指定します
4. --workspace <name> フラグを使って特定のワークスペースを有効にします
5. ui5 tree を実行して依存関係の解決を確認します
6. 詳細は references/configuration.md（ワークスペースのセクション）を参照してください

ワークフロー 5：UI5 CLI v4 への移行

使用する場面：UI5 CLI v3 から v4 にアップグレードする場合。

前提条件：

• Node.js v20.11.0+ または v22.0.0+ であることを確認します
• npm v8.0.0+ であることを確認します

手順：

1. CLI を更新します：npm install --save-dev @ui5/cli@latest
2. ui5.yaml の specVersion を "4.0" に更新します
3. references/migration-guides.md で破壊的変更を確認します
4. usePredefineCalls バンドルオプションがある場合は削除します
5. モダンな読み込み方式を使うため、バンドルセクションを async: true に更新します
6. ビルドをテストします：ui5 build --all
7. サーバーをテストします：ui5 serve
8. アプリケーションが正常に動作することを確認します

選択フロー

フレームワーク選択の判断

質問：どのフレームワークを使うべきですか？

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.

ビルドタイプ選択の判断

質問：どのビルドタイプを使うべきですか？

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

カスタム拡張の判断

質問：カスタムタスクとミドルウェアのどちらを作成すべきですか？

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/ui5.yaml.application：アプリケーションの完全な構成
• templates/ui5.yaml.library：ライブラリの完全な構成
• templates/ui5-workspace.yaml：モノレポのワークスペース設定
• templates/custom-task-template.js：カスタムビルドタスクのひな形
• templates/custom-middleware-template.js：カスタムサーバーミドルウェアのひな形

重要な注意事項

仕様バージョン

UI5 CLI は仕様バージョンを使用して機能を管理します。

• 4.0：現在のメジャーバージョン（CLI v4.0.55 で検証済み、Node.js v20.11.0 以降が必要）
• 3.0-3.2：CLI v3.0.0 以降と互換性があります
• 2.0-2.6：CLI v2.0.0 以降と互換性があります
• 0.1-1.1：レガシーバージョン（自動移行を試みます）

新しいプロジェクトでは、常に最新の specVersion を使用してください。

フレームワークのバージョン要件

• OpenUI5：最小バージョン 1.52.5
• SAPUI5：最小バージョン 1.76.0

開発とビルド

重要：開発中は常に ui5 build ではなく ui5 serve を使用してください。ビルドは本番環境へのデプロイ時にのみ実行してください。開発サーバーには次の利点があります。

• リロード時間の短縮
• リソースのオンザフライ処理
• デバッグ体験の向上
• 依存関係の自動解決

グローバルインストールとローカルインストール

UI5 CLI がグローバルとローカルの両方にインストールされている場合、ローカルバージョンが自動的に優先されます。これにより、プロジェクトごとに異なる CLI バージョンを使用できます。

動作を上書きする場合：UI5_CLI_NO_LOCAL=X ui5 serve

キャッシュ管理

UI5 CLI はフレームワークのバージョンを ~/.ui5/ にキャッシュします（ui5DataDir で設定可能）。

キャッシュをクリアするには：rm -rf ~/.ui5/framework/

既知の問題と制限事項

ECMAScript モジュールの制限

UI5 CLI は import／export 構文を使用する JavaScript モジュールをサポートしていません。すべてのモジュールで sap.ui.define 形式を使用する必要があります。

サポート対象外：

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

サポート対象：

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

テンプレートリテラルの制限

テンプレートリテラル内の式は、次の箇所では使用できません。

• 依存関係の宣言
• Smart Template 名
• ライブラリの初期化呼び出し

サポート対象外：

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

バンドルの制限（v4.0 以降）

「トップレベルスコープ」を必要とする JavaScript モジュールは、文字列としてバンドルできません。エラーログが記録され、バンドルから除外されます。

マニフェストのバージョン互換性

UI5 1.71 では、supportedLocales の生成時に、マニフェストの _version プロパティを 1.17.0 以下にする必要があります。UI5 フレームワークのバージョンに合わせてマニフェストのバージョンを更新してください。

トラブルシューティングのクイックリファレンス

詳細なトラブルシューティングについては、references/troubleshooting.md を参照してください。

よくある問題

問題：HTTP サーバーへのアクセス時に Chrome で ERR_SSL_PROTOCOL_ERROR が発生する

解決策：Chrome は HSTS により HTTPS を強制します。HSTS の設定をクリアしてください。

1. chrome://net-internals/#hsts に移動します
2. ドメイン（例：localhost）を入力します
3. 「Delete」をクリックします

問題：~/.ui5/ のディスク使用量が過剰になる

解決策：キャッシュされたフレームワークバージョンをクリアしてください。

rm -rf ~/.ui5/framework/

問題：「TypeError: invalid input」でビルドに失敗する

解決策：マニフェストの _version と UI5 フレームワークのバージョンとの互換性を確認してください。UI5 1.71 では、マニフェストのバージョンに 1.17.0 以下を使用してください。

問題：カスタムタスクが実行されない

解決策：タスクの構成を確認してください。

1. タスクが ui5.yaml で正しく定義されていることを確認します
2. beforeTask または afterTask が有効なタスク名を参照していることを確認します
3. タスクファイルが正しいシグネチャの非同期関数をエクスポートしていることを確認します
4. 詳細なログを取得するには ui5 build --verbose を使用します

環境変数

• UI5_LOG_LVL：ログレベルを設定します（silent/error/warn/info/perf/verbose/silly）
• UI5_DATA_DIR：デフォルトのデータディレクトリ（~/.ui5）を上書きします
• UI5_CLI_NO_LOCAL：ローカル CLI の優先を無効にします（グローバルを使用）

例：

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

ベストプラクティス

1. ui5.yaml と package.json は必ずバージョン管理にコミットします
2. プロジェクトの一貫性を保つため、ローカルの CLI をインストールします（--save-dev）
3. 本番ビルドではフレームワークのバージョンを固定します
4. モノレポのセットアップでは、npm linking の代わりにワークスペースを使用します
5. 開発中はHTTP/2 を有効にします（ui5 serve --h2）
6. 本番環境ではクリーンビルドを実行します（ui5 build --clean-dest --all）
7. コミット前に設定を検証します（検証スクリプトを使用）
8. CSP ポリシーを使用する場合は、複数のブラウザーでテストします
9. カスタムタスクとミドルウェアをプロジェクトの README に記載します
10. 最新の機能や修正を活用できるよう、CLI を最新の状態に保ちます

追加リソース

• 公式ドキュメント：https://ui5.github.io/cli/stable/
• API リファレンス：https://ui5.github.io/cli/v4/api/
• JSON スキーマ：https://ui5.github.io/cli/schema/ui5.yaml.json
• GitHub リポジトリ：https://github.com/SAP/ui5-tooling
• SAP コミュニティ：https://community.sap.com/
• npm レジストリ：https://www.npmjs.com/package/@ui5/cli

同梱リソース

リファレンスドキュメント

• references/cli-commands.md - CLI コマンドの完全なリファレンス
• references/configuration.md - 設定オプションと ui5.yaml
• references/project-structures.md - プロジェクト構造のパターン
• references/server-features.md - 開発サーバーの機能
• references/build-process.md - ビルドプロセスと最適化
• references/es-support.md - ES モジュールのサポート
• references/extensibility.md - 拡張性オプション
• references/code-analysis.md - コード解析ツール
• references/migration-guides.md - 旧バージョンからの移行
• references/troubleshooting.md - よくある問題と解決策
• references/benchmarking.md - パフォーマンスのベンチマーク

テンプレート

• templates/ui5.yaml.application - アプリケーション設定テンプレート
• templates/ui5.yaml.library - ライブラリ設定テンプレート
• templates/ui5-workspace.yaml - ワークスペース設定テンプレート
• templates/custom-task-template.js - カスタムタスクのひな形
• templates/custom-middleware-template.js - カスタムミドルウェアのひな形

バージョン情報

• 対象 CLI バージョン：4.0.55+
• 最終更新日：2026-05-31
• 次回レビュー：2026-02-21（四半期ごと）

---

このスキルは、Anthropic Agent Skills の公式ベストプラクティスと SAP UI5 CLI のドキュメント標準に準拠しています。