Skip to content

Configuration

A projects UI5 Tooling configuration is typically located in a YAML file named ui5.yaml, located in the root directory.

Info

This document describes the configuration of UI5 Tooling based projects and extensions. It represents Specification Version 2.2.

Validation / IDE support

Starting with specification version 2.0 the configuration is validated according to a JSON schema.
The current version of the schema can be found here: https://sap.github.io/ui5-tooling/schema/ui5.yaml.json

The schema is also part of the JSON Schema Store catalog which is used by the YAML Language Server.
See the list of clients to find extensions for various IDEs and editors.

Example

specVersion: "2.2"
type: application|library|theme-library|module
metadata:
  name: some.project.name

General Configuration

A project must define a specification version (specVersion), to which its configuration is compatible to. Also see Specification Versions.

In addition, a project must define a type. This can be either application, library, theme-library (since Specification Version 1.1) or module. The type defines the default path mappings and build tasks. See UI5 Builder: Types for details.

Example

specVersion: "2.2"
type: application
specVersion: "2.2"
type: library
specVersion: "2.2"
type: theme-library
specVersion: "2.2"
type: module

Metadata

Example

metadata:
  name: my.company.project
  copyright: |-
   My Project
    * (c) Copyright 2009-${currentYear} My Company
    * Licensed under the XYZ License, Version n - see LICENSE.txt.

name

A project must have a name and might define a copyright string.

In the UI5 Tooling, a project is typically identified by the configured name. It must be unique and should ideally follow a namespace scheme like company.businessarea.project.

A given copyright string will be used to fill placeholders like ${copyright} and @copyright@ in a projects source code. |- is a way to define a multi line string in YAML. For details, please check the YAML Specification.
Inside the copyright string, you can use the placeholder ${currentYear} which will be replaced with the current year.

deprecated

In case your project is deprecated you may also define a property deprecated: true. In projects that have a direct dependency to your project, UI5 Tooling will then display a deprecation warning.

Resources

Path Mapping

Depending on the project type, UI5 Tooling expects your projects source files to be located in certain directories.

If your project's sources are located in different directories, you need to configure the path mapping accordingly. Depending on the type of project, there are several different path mappings available.

Note that all configured paths must be written in POSIX (i.e. using only forward slashes /) and relative to the project's root directory.

Available Path Mappings

  • webapp: Mapped to runtime path / (root)

Default configuration:

resources:
  configuration:
    paths:
      webapp: webapp

  • src: Mapped to runtime path /resources
  • test: Mapped to runtime path /test-resources

Default configuration:

resources:
  configuration:
    paths:
      src: src
      test: test

Any virtual paths can be mapped to any physical path.

However, it is recommended that modules include their namespace in the virtual path and use the /resources prefix (e.g. /resources/my/library/module-xy/).

Example configuration:

resources:
  configuration:
    paths:
      /resources/my/library/module-xy/: lib
      /resources/my/library/module-xy-min/: dist

Example

For an application project with the following directory structure, you need the path mapping configuration given below:

Directory Structure

my-app/
\_ ui5.yaml
\_ lib/
  \_ js/
    \_ app/

Path Mapping Configuration

resources:
  configuration:
    paths:
      webapp: lib/js/app

Encoding of *.properties files

Info

This configuration is available since UI5 CLI v1.7.0

Example

resources:
  configuration:
    propertiesFileSourceEncoding: UTF-8
resources:
  configuration:
    propertiesFileSourceEncoding: ISO-8859-1

By default the UI5 Tooling expects different encodings for *.properties i18n files, depending on the project's specification version:

Specification Version Default propertiesFileSourceEncoding
2.0+ UTF-8
0.1, 1.0 or 1.1 ISO-8859-1

If your project uses a different encoding for *.properties files, you need to set the propertiesFileSourceEncoding configuration property.

The UI5 Tooling will read the corresponding files of the project in the given encoding. Any non-ASCII characters will be replaced with the respective Unicode escape sequences. This allows you to deploy the resulting files to any environment, independent of how it expects *.properties files to be encoded. Please refer to RFC 7 for details.

Custom Configuration

Info

This configuration is available since UI5 CLI v2.2.0 and applies only to projects defining Specification Version 2.1 or higher.

Example

customConfiguration:
  myTool:
    key: value
  myOtherTool:
    otherKey: otherValue

Custom configuration that is ignored by the UI5 Tooling.
This can be used to store UI5 specific configuration for third-party tools.

The "customConfiguration" value must be an object.
For third-party tools it is recommended to follow a namespace-like structure.

Framework Configuration

Info

This configuration is available since UI5 CLI v2.0.0 and applies only to projects defining Specification Version 2.0 or higher.

Define your project's framework dependencies.

Framework and Version

In your project's framework configuration you must define whether you want to use the OpenUI5 or the SAPUI5 framework and which version:

framework:
  name: OpenUI5
  version: 1.82.0
framework:
  name: SAPUI5
  version: 1.82.0

If you are not sure which framework is right for you, see our documentation on the differences between OpenUI5 and SAPUI5.

You can find an overview of the available versions for each framework here:

Info

Projects that use the OpenUI5 framework cannot depend on projects that use the SAPUI5 framework.

Dependencies

Example

specVersion: "2.2"
type: application
metadata:
  name: my.company.app
framework:
  name: OpenUI5
  version: 1.82.0
  libraries:
    - name: sap.ui.core
    - name: sap.m
    - name: sap.ui.table
    - name: themelib_sap_fiori_3
specVersion: "2.2"
type: library
metadata:
  name: my.company.library
framework:
  name: SAPUI5
  version: 1.82.0
  libraries:
    - name: sap.ui.core
    - name: sap.m
    - name: themelib_sap_belize
      optional: true
    - name: themelib_sap_bluecrystal
      optional: true
    - name: themelib_sap_fiori_3
      optional: true

When building an application depending on this library as well as one of the theme libraries, only that theme is built for this library.

Runtime Dependencies

All libraries required by your project must be listed in the libraries section of the framework configuration:

framework:
  name: OpenUI5
  version: 1.82.0
  libraries:
    - name: sap.ui.core
    - name: sap.m
    - name: sap.ui.table
framework:
  name: SAPUI5
  version: 1.82.0
  libraries:
    - name: sap.ui.core
    - name: sap.m
    - name: sap.ui.comp

Development Dependencies

Development dependencies are only installed if the project defining them is the current root project. They are typically only required during the development of the project.

  libraries:
    - name: sap.ushell
      development: true

Note that a development dependency cannot be optional and vice versa.

Optional Dependencies

Optional dependencies are installed either if the project defining them is the current root project or if the dependency is already part of the current dependency tree. A typical use case is libraries defining optional dependencies to all theme libraries they support. You can choose which theme library to use by the application that is consuming the library by declaring it as a non-optional dependency.

  libraries:
    - name: themelib_sap_fiori_3
      optional: true

Build Configuration

Exclude Resources

Example

builder:
  resources:
    excludes:
      - "/resources/some/project/name/test_results/**"
      - "/test-resources/**"
      - "!/test-resources/some/project/name/demo-app/**"

You can exclude a projects resources from the build process using a list of glob patterns. Matching resources will be ignored by the builder and all build tasks.

Patterns are applied to the virtual path of resources (i.e. the UI5 runtime paths). Exclude patterns are always applied after any includes.

Cachebuster

Example

builder:
  cachebuster:
    signatureType: time
builder:
  cachebuster:
    signatureType: hash

By default, the generated cachebuster info file signatures are based on timestamps (time). In setups like CI environments, a mechanism based on file hashes (hash) might be more reliable. Also see PR #241 for more details.

Component Preload Generation

For projects of type application a Component-preload.js bundle is generated by default.
You can override this default behavior by defining a componentPreload configuration.

For projects of type library there is no Component Preload created by default.
However you can define a componentPreload configuration to create Component Preload bundles. Those will be created in addition to the library-preload.js bundle.

There are two ways of including components, which can also be used in combination with each other:

paths

The paths option takes one or multiple patterns. For every matched file a separate Component-preload.js will be generated. Patterns are always applied relative to the project's virtual source directory /resources/

Example

builder:
  componentPreload:
    paths:
        - "my/great/app/**/Component.js"

namespaces

The namespaces option takes one or multiple component namespaces, which correspond to the directory structures:

Example

builder:
  componentPreload:
    namespaces:
        - "my/great/app/componentOne"
        - "my/great/app/componentTwo"

Custom Tasks

Example

builder:
  customTasks:
    - name: custom-task-1
      beforeTask: replaceCopyright
      configuration:
        some-key: some value
    - name: custom-task-2
      afterTask: custom-task-1
      configuration:
        color: blue

You can define custom build tasks that will be executed for the project. Please refer to the Custom Tasks Documentation for a detailed explanation and examples of the build extensibility.

Each customTasks entry must define the name of the custom task as defined in its metadata.name property.

In addition, the execution order needs to be defined by referencing a standard task or an already configured custom task using the afterTask or beforeTask property.

Optionally, arbitrary configuration can be passed to the custom task.

JSDoc

Example

builder:
  jsdoc:
    excludes:
      - "some/project/name/thirdparty/**"

You can exclude the resources of a project from the JSDoc build process using a list of glob patterns. Matching resources will be ignored by the JSDoc build task.

Patterns are always applied relative to the project's virtual source directory /resources/.

These excludes are applied before any general builder excludes that have been defined in builder.resources.excludes.

Server Configuration

Example

server:
  settings:
    httpPort: 1337
    httpsPort: 1443

By default, UI5 Tooling will serve applications using Port 8080. When running in HTTP/2 or HTTPS mode, Port 8443 will be used.

If the default port is already in use, the next highest free port will be used.

A project can also configure alternative default ports. If the configured port is already in use, an error will be thrown.

The default and configured server ports can always be overwritten with the CLI parameter --port.

Extension Configuration

Example

specVersion: "2.2"
type: application
metadata:
  name: my.application
---
specVersion: "2.2"
kind: extension
type: project-shim
metadata:
  name: my.application.thirdparty
shims:
  configurations:
    lodash:
      specVersion: "2.2"
      type: module
      metadata:
        name: lodash
      resources:
        configuration:
          paths:
            /resources/my/application/thirdparty/: ""

Extensions configuration can be added to any projects ui5.yaml. For better readability, it should to be located after the projects configuration, separated by three dashes "---".

In cases where an extension shall be reused across multiple projects you can make it a module itself and have its configuration in a standalone ui5.yaml located inside that module.

Extensions can be identified by the kind: extension configuration. Note that if no kind configuration is given, project is assumed.

Available Extensions

Custom Bundling

Example

builder:
  bundles:
    - bundleDefinition:
        name: "sap-ui-custom.js"
        defaultFileTypes:
          - ".js"
        sections:
          - mode: raw
            filters:
            - ui5loader-autoconfig.js
            resolve: true
            sort: true
      bundleOptions:
        optimize: true
    - bundleDefinition:
        name: "app.js"
        defaultFileTypes:
          - ".js"
        sections:
          - mode: preload
            filters:
              - some/app/Component.js
            resolve: true
            sort: true
          - mode: provided
            filters:
            - ui5loader-autoconfig.js
            resolve: true
      bundleOptions:
        optimize: true

Custom bundles can be defined in the ui5.yaml. Within the builder/bundles configuration a list of bundleDefinitions can be described.

Properties

bundles

A list of bundle definitions. A bundleDefinition contains of the following options:

  • name: The module bundle name
  • defaultFileTypes: List of default file types which should be included in the bundle
  • sections: A list of module bundle definition sections. Each section specifies an embedding technology (see API-Reference) and lists the resources that should be in- or excluded from the section.
    • mode: The embedding technology (e.g. provided, raw, preload)
    • filters: List of resources as glob patterns that should be in- or excluded. A pattern either contains of a trailing slash / or single * and double ** asterisks which denote an arbitrary number of characters or folder names. Exludes should be marked with a leading exclamation mark '!'. The order of filters is relevant, a later exclusion overrides an earlier inclusion and vice versa.
    • resolve: Setting resolve to true will also include all (transitive) dependencies of the files
    • resolveConditional: Whether conditional dependencies of modules should be resolved and added to the module set for this section. By default set to false
    • declareRawModules: Whether raw modules should be declared after jQuery.sap.global became available. With the usage of the ui5loader, this flag should be set to 'false'. By default set to false
    • renderer: Whether renderers for controls should be added to the module set. By default set to false
    • sort: By default, modules are sorted by their dependencies. The sorting can be suppressed by setting the option to false

bundleOptions

  • optimize: By default set to false. If set to true, the module bundle gets minified
  • decorateBootstrapModule: By default set to false. If set to true, the module will be decorated with an optimization marker
  • addTryCatchRestartWrapper: By default set to false. If set to true, bootable module bundles gets wrapped with a try/catch to filter "Restart" errors
  • usePredefineCalls: If set to true, sap.ui.predefine is used for UI5 modules
  • numberOfParts: By default set to 1. The number of parts into which a module bundle should be splitted

Specification Versions

A project must define a Specification Version by setting the specVersion property. The UI5 Tooling uses this information to detect whether the currently installed version is compatible to a projects configuration.

specVersion: "2.2"
[...]

To use new features, a project might need to update the specVersion property.

For a given Specification Version MAJOR.MINOR we will increment:

  1. MAJOR when there are breaking changes that might require additional actions by the project maintainer
  2. MINOR when adding new features that are fully backward compatible

All changes are documented below.

Compatibility Matrix

Unless otherwise noted in the table below, the UI5 Tooling modules are backward compatible.

Version UI5 CLI Release
2.2 v2.4.0+
2.1 v2.2.0+
2.0 v2.0.0+
1.1 v1.13.0+
1.0 v1.0.0+
0.1 v0.0.1+

Specification Version 2.2

Features:

Specification Version 2.2 projects are supported by UI5 CLI v2.4.0 and above.

Specification Version 2.1

Features:

Specification Version 2.1 projects are supported by UI5 CLI v2.2.0 and above.

Specification Version 2.0

Breaking changes:

  • Adds and enforces schema validation of the ui5.yaml
  • By default the encoding of *.properties files is expected to be UTF-8 (as opposed to ISO-8859-1 in projects defining specification versions below 2.0)

Features:

  • Adds support for the "framework" configuration to consume SAPUI5 libraries.

Specification Version 2.0 projects are supported by UI5 CLI v2.0.0 and above.

Specification Version 1.1

Features:

  • Adds support for the theme-library type.

Specification Version 1.1 projects are supported by UI5 CLI v1.13.0 and above.

Specification Version 1.0

First stable release.

Specification Version 1.0 projects are supported by UI5 CLI v1.0.0 and above.

Specification Version 0.1

Initial version.

Specification Version 0.1 projects are compatible with UI5 CLI v0.0.1 and above.