Migrate to v3¶

Node.js and npm Version Support¶

This release requires Node.js versions v16.18.0, v18.12.0 or higher as well as npm v8 or higher. Support for older Node.js and npm releases has been dropped and will cause an error to be shown.

Specification Versions Support¶

Going forward, only projects with Specification Versions 2.0 and higher are supported.

In case a legacy specification version is detected, an automatic migration is attempted. This means your old projects might still work. Unless they have non-standard configuration in their ui5.yaml.

Changes for Projects¶

For projects defining the latest Specification Versions 3.0 and higher, some changes apply:

• Breaking Change: The metadata.name property is now restricted to contain only certain characters and no uppercase letters. See Configuration: name for details

See also Configuration: Specification Version 3.0.

Changes for Extensions¶

For extensions defining the latest Specification Versions 3.0 and higher, some changes and improvements apply:

• Breaking Change: Custom Tasks need to request access to dependency resources
  • By default, resources of dependencies can't be accessed. A custom task requiring such access needs to implement a callback function with the export name determineRequiredDependencies. In this function it can define the scope of dependency-access. Please refer to the Custom Task: Required Dependencies documentation for details
• Breaking Change: The metadata.name property is now restricted to contain only certain characters and no uppercase letters. See Configuration: name for details
• Features: Enhanced TaskUtil and MiddlewareUtil API
  • For example providing access to a project's root directory, or dependencies
  • See also Custom Tasks and Custom Server Middleware

Changes to Dependency Configuration¶

{
    [...]
-     "ui5": {
-       "dependencies": [
-         "my-package"
-       ]
-     }
    [...]
}

Changes to Module API¶

The normalizer and projectTree modules have been removed. The builder API has been moved from @ui5/builder to @ui5/project.

The JSON based, internal representation of a project dependency tree has been replaced with a graph. This is the result of a major refactoring of @ui5/project which lead to a series of API changes.

Also the @ui5/server API has been changed. Instead of a tree, it now only accepts a graph instance as the first parameter.

Migrate Your Code¶

The tooling modules such as @ui5/builder, etc. have been transformed to ES Modules ("ESM"). Therefore, they no longer use a CommonJS export and cannot be included via require. If your code is in CommonJS format, it needs to use dynamic imports or be converted to ES Modules.

Old: @ui5/project v2

const {normalizer} = require("@ui5/project");
const {builder} = require("@ui5/builder");

const tree = await normalizer.generateProjectTree({cwd: "."});

await builder.build({
    tree,
    destPath: "./dist",
    buildDependencies: true,
});

New: @ui5/project v3

import {graphFromPackageDependencies} from "@ui5/project/graph";

let graph = await graphFromPackageDependencies({cwd: "."});

await graph.build({
    destPath: "./dist",
    includedDependencies: ["*"], // Parameter "buildDependencies" has been removed
});

// Since CommonJS does not suport top-level await, the code must be wrapped in an asynchronous function
async function buildProject() {
    const {graphFromPackageDependencies} = await import("@ui5/project/graph");

    let graph = await graphFromPackageDependencies({cwd: "."});

    await graph.build({
        destPath: "./dist",
        includedDependencies: ["*"], // Parameter "buildDependencies" has been removed
    });
}

Changes to @ui5/cli¶

• The CLI option --translator has been removed. For static dependency resolution, use the new option --dependency-definition to provide a file with static dependency information.
• The ui5 build dev command has been removed. Use ui5 build --exclude-task=* --include-task=replaceCopyright replaceVersion replaceBuildtime buildThemes instead.

JSDoc Processor Fails When JSDoc Reports an Error¶

The jsdocGenerator processor and the corresponding generateJsdoc task will now throw an error when JSDoc reports an error (exit code != 0). This will also fail the build when running ui5 build jsdoc.

Always Building Required Dependencies¶

If any of a project's build tasks requires access to resources of the project's dependencies, UI5 Tooling v3 will now always build that dependency upfront.

This ensures that tasks always access processed resources and never the raw sources of a dependency. Resulting in better reproducibility of build results and resolving common issues.

Especially for projects of type library, where standard tasks like buildThemes always require dependency access, UI5 Tooling will now always build all dependencies.

In the future, a caching mechanism should help and improve build times with this new behavior.

Removal of Standard Tasks and Processors¶

The following tasks have been removed:

• createDebugFiles
• generateManifestBundle
• uglify

The following processors have been removed:

• debugFileCreator
• manifestBundler
• resourceCopier
• uglifier

Task Migration

Updated list of standard tasks:

Disabled tasks can be activated by certain build modes, the project configuration, or by using the --include-task CLI parameter. See footnotes where given

¹ Enabled in jsdoc build, which disables most of the other tasks
² Enabled for projects defining a component preload configuration
³ Enabled in self-contained build, which disables generateComponentPreload and generateLibraryPreload
⁴ Enabled for projects defining a bundle configuration
⁵ Can be enabled for framework projects via the includeTask option. For other projects, this task is skipped

Removal of Standard Middleware¶

The following middleware has been removed from the standard middlewares list:

• connectUi5Proxy

Middleware Migration