@ui5/project/build/helpers/TaskUtil
@ui5/project/build/helpers/TaskUtil
Convenience functions for UI5 tasks. An instance of this class is passed to every standard UI5 task that requires it.
Custom tasks that define a specification version >= 2.2 will receive an interface to an instance of this class when called. The set of available functions on that interface depends on the specification version defined for the extension.
Members
STANDARD_TAGS :@ui5/project/build/helpers/TaskUtil~StandardBuildTags
Source: project/lib/build/helpers/TaskUtil.js, line 59
Type:
resourceFactory :@ui5/project/build/helpers/TaskUtil~resourceFactory
Description: Provides limited access to @ui5/fs/resourceFactory functions
This attribute is only available to custom task extensions defining Specification Version 3.0 and above.
Source: project/lib/build/helpers/TaskUtil.js, line 377
Provides limited access to @ui5/fs/resourceFactory functions
This attribute is only available to custom task extensions defining Specification Version 3.0 and above.
Type:
Methods
clearTag(resource, tag)
Description: Clears the value of a tag stored for the given resource's path. It's like the tag was never set for that resource.
This method is only available to custom task extensions defining Specification Version 2.2 and above.
Source: project/lib/build/helpers/TaskUtil.js, line 132
Parameters:
| Name | Type | Description |
|---|---|---|
resource | @ui5/fs/Resource | Resource-instance the tag should be cleared for |
tag | string | Tag |
getBuildTime() → {Date}
Description: Returns the build run's shared timestamp as a raw Date.
The value is the single timestamp fixed once per build run (shared by every project and task in the run), the same source getTime quantizes.
Unlike getTime, this read is deliberately not tracked as a build-cache input: the MonitoredTaskUtil passes it through untracked, so its value never folds into the task's cache signature. A cached result therefore keeps the timestamp it embedded on the build that produced it, rather than re-running because the timestamp advanced. That staleness is intended: a build timestamp changes on every build, so tracking it would force a cache miss every time and defeat caching for any task that reads it. Read through getTime instead when the output should re-run once a time bucket rolls over (for example a copyright year).
This method is only available to custom task extensions defining Specification Version 5.0 and above.
Source: project/lib/build/helpers/TaskUtil.js, line 222
Returns:
The current build run's timestamp
Type: Date
getDependencies(projectNameopt) → {Array<string>}
Description: Retrieve a list of direct dependencies of a given project from the dependency graph. Note that this list does not include transitive dependencies.
This method is only available to custom task extensions defining Specification Version 3.0 and above.
Source: project/lib/build/helpers/TaskUtil.js, line 342
Parameters:
| Name | Type | Attributes | Description |
|---|---|---|---|
projectName | string | optional | Name of the project to retrieve. Defaults to the project currently being built |
Throws:
If the requested project is unknown to the graph
Type: Error
Returns:
Names of all direct dependencies
Type: Array<string>
getEnv(name) → {string|undefined}
Description: Reads an environment variable.
Tasks whose output depends on an environment variable must read it through this method rather than accessing process.env directly. During a build the task receives a MonitoredTaskUtil that records the read and folds it into the task's build-cache signature, so that changing the variable between builds invalidates the task's cached result (the same way a changed resource does). Reading process.env directly is not tracked and can lead to a stale cached result being served.
This method is only available to custom task extensions defining Specification Version 5.0 and above.
Source: project/lib/build/helpers/TaskUtil.js, line 160
Parameters:
| Name | Type | Description |
|---|---|---|
name | string | Environment variable name |
Returns:
The environment variable value, or undefined if unset
Type: string | undefined
getProject(projectNameOrResourceopt) → {@ui5/project/build/helpers/TaskUtil~ProjectInterface|undefined}
Description: Retrieve a single project from the dependency graph
This method is only available to custom task extensions defining Specification Version 3.0 and above.
Source: project/lib/build/helpers/TaskUtil.js, line 315
Parameters:
| Name | Type | Attributes | Description |
|---|---|---|---|
projectNameOrResource | string | @ui5/fs/Resource | optional | Name of the project to retrieve or a Resource instance to retrieve the associated project for. Defaults to the name of the project currently being built |
Returns:
Specification Version-dependent interface to the Project instance or undefined if the project name is unknown or the provided resource is not associated with any project.
Type: @ui5/project/build/helpers/TaskUtil~ProjectInterface | undefined
getTag(resource, tag) → {string|boolean|integer|undefined}
Description: Retrieves the value for a stored tag. If no value is stored, undefined is returned.
This method is only available to custom task extensions defining Specification Version 2.2 and above.
Source: project/lib/build/helpers/TaskUtil.js, line 111
Parameters:
| Name | Type | Description |
|---|---|---|
resource | @ui5/fs/Resource | Resource-instance the tag should be retrieved for |
tag | string | Name of the tag |
Returns:
Tag value for the given resource. undefined if no value is available
Type: string | boolean | integer | undefined
getTime(granularity) → {string}
Description: Reads the build's time quantized to a fixed granularity.
The returned value comes from a single timestamp fixed once per build run (shared by every project and task in the run), not a fresh Date per call, so all time reads within a run agree.
Tasks whose output depends on the current time (for example replaceCopyright, which expands ${currentYear}) must read it through this method rather than calling new Date() directly. During a build the task receives a MonitoredTaskUtil that records the read and folds it into the task's build-cache signature, so a cached result re-runs once the time bucket rolls over (a "year"-granularity result is re-run at the next calendar year). A direct Date read is not tracked and can serve a stale result.
The granularity is the contract: it names the bucket at which the output is stable. A millisecond-precision read would change on every build and miss the cache every time, so this method never returns a raw timestamp. Reading at "year" means "re-run only when the year changes".
This method is only available to custom task extensions defining Specification Version 5.0 and above.
Source: project/lib/build/helpers/TaskUtil.js, line 196
Parameters:
| Name | Type | Description |
|---|---|---|
granularity | string | Time bucket, one of "year", "month","day", "hour" |
Throws:
If the granularity is not one of the supported buckets
Type: Error
Returns:
Current time quantized to the granularity, e.g. "2026" for "year" or "2026-09-25T14" for "hour"
Type: string
isRootProject() → {boolean}
Description: Check whether the project currently being built is the root project.
This method is only available to custom task extensions defining Specification Version 2.2 and above.
Source: project/lib/build/helpers/TaskUtil.js, line 236
Returns:
true if the currently built project is the root project
Type: boolean
registerCleanupTask(callback)
Description: Register a function that must be executed once the build is finished. This can be used to, for example, clean up files temporarily created on the file system. If the callback returns a Promise, it will be waited for. It will also be executed in cases where the build has failed or has been aborted.
This method is only available to custom task extensions defining Specification Version 2.2 and above.
Source: project/lib/build/helpers/TaskUtil.js, line 275
Parameters:
| Name | Type | Description |
|---|---|---|
callback | @ui5/project/build/helpers/TaskUtil~cleanupTaskCallback | Callback to register; it will be waited for if it returns a Promise |
setTag(resource, tag, valueopt)
Description: Stores a tag with value for a given resource's path. Note that the tag is independent of the supplied resource instance. For two resource instances with the same path, the same tag value is returned. If the path of a resource is changed, any tag information previously stored for that resource is lost.
This method is only available to custom task extensions defining Specification Version 2.2 and above.
Source: project/lib/build/helpers/TaskUtil.js, line 88
Parameters:
| Name | Type | Attributes | Default | Description |
|---|---|---|---|---|
resource | @ui5/fs/Resource | Resource-instance the tag should be stored for | ||
tag | string | Name of the tag. Currently only the STANDARD_TAGS are allowed | ||
value | string | boolean | integer | optional | true | Tag value. Must be primitive |
Type Definitions
ProjectInterface
Description: Specification Version-dependent Project interface. For details on individual functions, see Project
Source: project/lib/build/helpers/TaskUtil.js, line 279
Properties:
| Name | Type | Description |
|---|---|---|
getType | function | Get the project type |
getName | function | Get the project name |
getVersion | function | Get the project version |
getNamespace | function | Get the project namespace |
getRootReader | function | Get the project rootReader |
getReader | function | Get the project reader |
getRootPath | function | Get the local File System path of the project's root directory |
getSourcePath | function | Get the local File System path of the project's source directory |
getCustomConfiguration | function | Get the project Custom Configuration |
isFrameworkProject | function | Check whether the project is a UI5-Framework project |
getFrameworkName | function | Get the project's framework name configuration |
getFrameworkVersion | function | Get the project's framework version configuration |
getFrameworkDependencies | function | Get the project's framework dependencies configuration |
Specification Version-dependent Project interface. For details on individual functions, see Project
Type:
- object
StandardBuildTags
Description: Standard Build Tags. See UI5 CLI RFC 0008 for details.
Source: project/lib/build/helpers/TaskUtil.js, line 26
Properties:
| Name | Type | Description |
|---|---|---|
OmitFromBuildResult | string | Setting this tag to true will prevent the resource from being written to the build target directory |
IsBundle | string | This tag identifies resources that contain (i.e. bundle) multiple other resources |
IsDebugVariant | string | This tag identifies resources that are a debug variant (typically named with a "-dbg" suffix) of another resource. This tag is visible to other projects |
HasDebugVariant | string | This tag identifies resources for which a debug variant has been created. This tag is visible to other projects |
Standard Build Tags. See UI5 CLI RFC 0008 for details.
Type:
- object
cleanupTaskCallback(force)
Description: Callback that is executed once the build has finished
Source: project/lib/build/helpers/TaskUtil.js, line 252
Parameters:
| Name | Type | Description |
|---|---|---|
force | boolean | Whether the cleanup callback should gracefully wait for certain jobs to be completed ( false)or enforce immediate termination ( true) |
resourceFactory
Description: Specification Version-dependent set of @ui5/fs/resourceFactory functions provided to tasks. For details on individual functions, see @ui5/fs/resourceFactory
Source: project/lib/build/helpers/TaskUtil.js, line 346
Properties:
| Name | Type | Description |
|---|---|---|
createResource | function | Creates a Resource. Accepts the same parameters as the Resource constructor. |
createReaderCollection | function | Creates a reader collection: ReaderCollection |
createReaderCollectionPrioritized | function | Creates a prioritized reader collection: ReaderCollectionPrioritized |
createFilterReader | function | Create a Filter-Reader with the given reader. |
createLinkReader | function | Create a Link-Reader with the given reader. |
createFlatReader | function | Create a Link-Reader where all requests are prefixed with /resources/<namespace>. |
Specification Version-dependent set of @ui5/fs/resourceFactory functions provided to tasks. For details on individual functions, see @ui5/fs/resourceFactory
Type:
- object