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.6.
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.6"
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.6"
type: application
specVersion: "2.6"
type: library
specVersion: "2.6"
type: theme-library
specVersion: "2.6"
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 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
.
copyright¶
A given copyright
string will be used to fill placeholders like ${copyright}
and @copyright@
in a project's source code. |-
is a way to define a multi line string in YAML. Check the YAML Specification for details.
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 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.
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 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:
- OpenUI5 Version Overview
- The lowest version supported by UI5 Tooling is 1.52.5
- SAPUI5 Version Overview
- The lowest version supported by UI5 Tooling is 1.76.0
Info
Projects that use the OpenUI5 framework cannot depend on projects that use the SAPUI5 framework.
Dependencies¶
Example
specVersion: "2.6"
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.6"
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. This bundle will contain most UI5 runtime-relevant resources of the component.
You can override this default behavior by defining a componentPreload
configuration.
For projects of type library
, no Component Preload is 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 to define the set of components for which preload bundles should be generated. You can either provide paths
(allowing patterns) or namespaces
. You can also combine both configuration options. Defining any of them overrides the default preload bundle generation for the root component of application
projects.
paths¶
Example
builder:
componentPreload:
paths:
- "my/awesome/app/**/Component.js"
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/
.
namespaces¶
Example
builder:
componentPreload:
namespaces:
- "my/awesome/app"
- "my/awesome/app/componentOne"
- "my/awesome/app/componentTwo"
The namespaces
option takes one or multiple component namespaces, which correspond to the directory structures.
excludes¶
Info
This configuration is available since UI5 CLI v2.10.0
and applies only to projects defining Specification Version 2.3 or higher.
Example
builder:
componentPreload:
excludes:
- "my/awesome/app/localService/**"
builder:
componentPreload:
namespaces:
- "my/awesome/app"
- "my/awesome/app/componentOne"
- "my/awesome/app/componentTwo"
excludes:
- "my/awesome/app/**/thirdparty/"
- "!my/awesome/app/componentTwo/thirdparty/NotExcluded.js"
List of modules declared as glob patterns (resource name patterns) that are excluded from the component preload bundles. Similarly to the use of a single *
or double **
asterisk, a pattern ending with a slash /
denotes an arbitrary number of characters or folder names. Re-includes have to be marked with a leading exclamation mark !
. The order of filters is relevant; a later inclusion overrides an earlier exclusion, and vice versa.
Note that patterns are always applied relative to the project's virtual source directory /resources/
. Re-includes must start with the namespace of the component they apply to.
Library Preload Generation¶
For projects of type library
a library-preload.js
bundle is generated by default. This bundle will contain most UI5 runtime-relevant resources of the library.
excludes¶
Info
This configuration is available since UI5 CLI v2.10.0
and applies only to projects defining Specification Version 2.3 or higher.
Example
builder:
libraryPreload:
excludes:
- "my/lib/thirdparty/"
- "!my/lib/thirdparty/NotExcluded.js"
List of modules declared as glob patterns (resource name patterns) that are excluded from library-preload.js
bundle. Similarly to the use of a single *
or double **
asterisk, a pattern ending with a slash /
denotes an arbitrary number of characters or folder names. Re-includes have to be marked with a leading exclamation mark !
. The order of filters is relevant; a later inclusion overrides an earlier exclusion, and vice versa.
Note that patterns are always applied relative to the project's virtual source directory /resources/
. Re-includes must start with the library's namespace.
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
.
Include Dependencies¶
Info
This configuration is available since UI5 CLI v2.12.0
and applies only to projects defining Specification Version 2.5 or higher.
Example
builder:
settings:
includeDependency:
- shimmed.thirdparty.library
includeDependencyRegExp:
- ^com\.namespace
includeDependencyTree:
- sap.m
You can include certain dependencies into the build process using the includeDependency
builder setting. By using includeDependencyRegExp
, a regular expression can be used, for example to specify a namespace to dynamically select a group of dependencies that have to be included into the build result. By using includeDependencyTree
, a selected dependency including all of its sub-dependencies is used.
This configuration can be overwritten more precisely with the CLI parameters --include-dependency
, --include-dependency-regexp
, --include-dependency-tree
, --exclude-dependency
, --exclude-dependency-regexp
and --exclude-dependency-tree
.
Minification¶
For projects of type application
and library
the minification is done for all JavaScript files. This minification includes by default the standard build tasks uglify
and createDebugFiles
.
excludes¶
Info
This configuration is available since UI5 CLI v2.14.0
and applies only to projects defining Specification Version 2.6 or higher.
Example
builder:
minification:
excludes:
- "my/lib/thirdparty/"
- "!my/lib/thirdparty/NotExcluded.js"
List of modules declared as glob patterns (resource name patterns) that are excluded from resource minification. Re-includes have to be marked with a leading exclamation mark !
. The order of filters is relevant; a later inclusion overrides an earlier exclusion, and vice versa.
Note that patterns are always applied relative to the project's virtual source directory /resources/
.
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.6"
type: application
metadata:
name: my.application
---
specVersion: "2.6"
kind: extension
type: project-shim
metadata:
name: my.application.thirdparty
shims:
configurations:
lodash:
specVersion: "2.6"
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"
sections:
- mode: raw
filters:
- ui5loader-autoconfig.js
resolve: true
sort: true
bundleOptions:
optimize: true
- bundleDefinition:
name: "app.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 namedefaultFileTypes
: List of default file types which should be included in the bundle. Defaults to:.js
,.control.xml
,.fragment.html
,.fragment.json
,.fragment.xml
,.view.html
,.view.json
and.view.xml
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 modules declared as glob patterns (resource name patterns) that are in- or excluded. Similarly to the use of a single*
or double**
asterisk, a pattern ending with a slash/
denotes an arbitrary number of characters or folder names. Excludes have to be marked with a leading exclamation mark!
. The order of filters is relevant; a later inclusion overrides an earlier exclusion, and vice versa.resolve
: Setting resolve totrue
will also include all (transitive) dependencies of the filesresolveConditional
: Whether conditional dependencies of modules should be resolved and added to the module set for this section. By default set tofalse
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 tofalse
renderer
: Whether renderers for controls should be added to the module set. By default set tofalse
sort
: By default, modules are sorted by their dependencies. The sorting can be suppressed by setting the option tofalse
bundleOptions
optimize
: By default set tofalse
. If set totrue
, the module bundle gets minifieddecorateBootstrapModule
: By default set tofalse
. If set totrue
, bootable bundles will be decorated with an optimization markeraddTryCatchRestartWrapper
: By default set tofalse
. If set totrue
, bootable bundles will be wrapped with a try/catch to filter "Restart" errorsusePredefineCalls
: If set totrue
,sap.ui.predefine
is used for UI5 modulesnumberOfParts
: By default set to1
. 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. UI5 Tooling uses this information to detect whether the currently installed version is compatible to a projects configuration.
specVersion: "2.6"
[...]
To use new features, a project might need to update the specVersion
property.
For a given Specification Version MAJOR.MINOR we will increment:
- MAJOR when there are breaking changes that might require additional actions by the project maintainer
- MINOR when adding new features that are fully backward compatible
All changes are documented below.
Compatibility Matrix¶
Unless otherwise noted in the table below, UI5 Tooling modules are backward compatible.
Version | UI5 CLI Release |
---|---|
2.6 | v2.14.0+ |
2.5 | v2.12.0+ |
2.4 | v2.11.0+ |
2.3 | v2.10.0+ |
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.6¶
Features:
- Adds support for
excludes
configuration for the application and library minification
Specification Version 2.6 projects are supported by UI5 CLI v2.14.0 and above.
Specification Version 2.5¶
Features:
- Adds support for the build configuration
includeDependency
- Allows server configuration in projects of type
module
Specification Version 2.5 projects are supported by UI5 CLI v2.12.0 and above.
Specification Version 2.4¶
Features:
- Adds support for
bundleInfo
mode in bundle definitions.
Specification Version 2.4 projects are supported by UI5 CLI v2.11.0 and above.
Specification Version 2.3¶
Features:
Specification Version 2.3 projects are supported by UI5 CLI v2.10.0 and above.
Specification Version 2.2¶
Features:
- Custom task extensions can make use of the
TaskUtil
Helper Class
Specification Version 2.2 projects are supported by UI5 CLI v2.4.0 and above.
Specification Version 2.1¶
Features:
- Adds support for the "customConfiguration" configuration
- Custom middleware extensions can make use of the
MiddlewareUtil
Helper Class
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 beUTF-8
(as opposed toISO-8859-1
in projects defining specification versions below 2.0)- A project can still explicitly configure the encoding of its
*.properties
files
- A project can still explicitly configure the encoding of its
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.