Ui5-tooling-modules NPM

UI5 Tooling Extensions for NPM Package Consumption

:wave: This is a community project and there is no official support for this package! Feel free to use it, open issues, contribute, and help answering questions.

The UI5 tooling extensions include a custom middleware and a custom task which allow to use NPM package names for AMD-like dependencies, e.g.:

# Install a dev dependency to Chart.js (https://www.chartjs.org/)
npm install chart.js

// use Chart.js as a AMD-like dependency
sap.ui.define([
  "chart.js"
], function(chartjs) {
  [...]
  alert(chartjs.version);
  [...]
})

Once the UI5 application is finally built, the Chart.js dependency will be copied into the dist/resources folder with the proper namespace. In case of Chart.js above, there is no namespace and thus the location will be dist/resources/chart.js.js.

Prerequisites

Requires at least @ui5/cli@3.0.0 (to support specVersion: "3.0")

:warning: UI5 Tooling Compatibility All releases of this tooling extension using the major version 3 require UI5 Tooling V3. Any previous releases below major version 3 (if available) also support older versions of the UI5 Tooling. But the usage of the latest UI5 Tooling is strongly recommended!

Install

npm install ui5-tooling-modules --save-dev

Configuration options (in `$yourapp/ui5.yaml`)

The following configuration options are relevant for the task and the middleware:

debug: boolean|string
Enables debug logging (defaults to false), by setting value to "verbose" the extension will log even more detailed
skipCache: boolean experimental feature For development scenarios, the module cache can be disabled by setting this option to true. Normally, if a module changes (e.g. bundledefs), this change is detected and the bundle is recreated. This just forces the regeneration always (defaults to false)
keepDynamicImports: boolean|String[] experimental feature An arrays of NPM package names for which the dynamic imports with a generic target module (e.g. import(anyUrl)) will not be converted into a require based polyfill. If the value is a boolean, it activates/deactivates the feature for all modules (by default it is active!). This experimental feature is useful in scenarios loading ES modules dynamically from generic URLs. All dynamic imports resolving a concrete module (e.g. import("jspdf")) will be converted into chunks and loaded with a require call.
skipTransform: boolean|String[] experimental feature Array of glob patterns to verify whether the module transformation should be skipped for the modules which are matching the glob pattern. If the value is a boolean then the transformation can be skipped in general by setting the value to true. The configuration can be incorporated from the customConfiguration of a dependency using that middleware, e.g. a library can provide its customConfiguration for the application project like this (and can reuse the configuration internally via YAML anchors):
```
specVersion: "3.0"
metadata:
  name: com.myorg.mylib
type: library
customConfiguration:
  ui5-tooling-modules: &cfgModules
    skipTransform:
      - "@luigi-project/container/dist/anypath/**"
builder:
  customTasks:
    - name: ui5-tooling-modules-task
      afterTask: replaceVersion
      configuration:
        <<: *cfgModules
```

inject: Map<String, String|String[]> experimental feature A map of Globals which are injected as imports to an NPM package to handle cases in which functions need to be poly- or ponyfilled. The configuration is aligned with definition of the Globals in the @rollup/plugin-inject:

configuration:
  inject:
    # import setImmediate from 'set-immediate-shim'
    setImmediate: set-immediate-shim
    # import { Promise } from 'es6-promise'
    Promise:
      - es6-promise
      - Promise
    # import { Promise as P } from 'es6-promise'
    P: 
      - es6-promise
      - Promise
    # import $ from 'jquery'
    $: jquery
    # import * as fs from 'fs'
    fs: 
      - 'fs'
      - '*'

minify: boolean experimental feature Flag to indicate that the generated code should be minified (in case of excluding thirdparty resources from minification in general, this option can be used to minify just the generated code)

The following configuration options are just relevant for the task:

prependPathMappings: boolean
Prepends the path mappings for the UI5 loader to the Component.js which allows to run the Component using 3rd party modules in e.g. Fiori launchpad environments (defaults to false)
addToNamespace: boolean Puts 3rd party modules into the namespace of the Component to make them Component-local. All used 3rd party modules will be moved into the sub-namespace thirdparty of the Component namespace at build time. With that option you can run your application using 3rd party modules in a Fiori launchpad environment. (defaults to false, disables prependPathMappings when set to true)
:warning: While this works great for any non-UI5 3rd party module, there are limitations for the consumption of UI5 modules from custom control 3rd party modules (NPM packages). The UI5 module names (used for Object.extend(...), aggregation types, ...) are not rewritten and this may cause issues. UI5 assumes that the used module path (slash syntax) is matching the module name (dot syntax). This can lead to issues for Object.isA(...) checks, Renderer lookups (when not inlined or referenced by module), or for any other API which derives the module name from the module path or vice versa.
removeScopePrefix: boolean Removes the scope prefix @ from the namespace/path of the 3rd party module when adding it to the namespace with the addToNamespace option.
providedDependencies: String[] An array of NPM package names which will be available in the development server via the middleware but will be ignored for the build process via the task. Provided dependencies are considered as being provided by the application runtime rather than it must be shipped with the current project. Provided dependencies will ignore any of the configurations above.
includeAssets: Map<String, String[]> experimental feature A map of NPM package names to list of glob patterns which defines the assets to be included. The list of glob patterns can be omitted in case of copying all resources of the NPM package.

The following configuration options are just relevant for the middleware:

watch: boolean experimental feature For development scenarios, the server is listening to changes of the source files of the project and its dependencies and triggers the generation of the bundle if the used NPM packages have been changed (defaults to true)

Usage

Define the dependency in $yourapp/package.json:

"devDependencies": {
    // ...
    "ui5-tooling-modules": "*"
    // ...
}

Configure it in $yourapp/ui5.yaml:

The configuration for the custom task:

builder:
  customTasks:
    - name: ui5-tooling-modules-task
      afterTask: replaceVersion

The configuration for the custom middleware:

server:
  customMiddleware:
    - name: ui5-tooling-modules-middleware
      afterMiddleware: compression

:warning: In case your application is using a proxy such fiori-tools-proxy, the proxy must run after ui5-tooling-modules-middleware middleware. Otherwise proxy will try to serve the resources for your installed npm package instead of ui5-tooling-modules-middleware. You can achieve this by setting afterMiddleware: ui5-tooling-modules-middleware in fiori-tools-proxy middleware.

:fire: TIP :fire:

YAML anchors are a great feature to avoid redundancies in .yaml files. You can share the configuration of the task and the middleware in the following way:

ui5.yaml

customConfiguration:
  ui5-tooling-modules: &cfgModules
    debug: true
    keepDynamicImports:
      - "@luigi-project/container"
[...]
server:
  customMiddleware:
    - name: ui5-tooling-modules-middleware
      afterMiddleware: compression
      configuration:
        <<: *cfgModules
[...]
builder:
  customTasks:
    - name: ui5-tooling-modules-task
      afterTask: replaceVersion
      configuration:
        <<: *cfgModules
        addToNamespace: true

With this approach you can ensure that you have a consistent configuration across your task and middleware.

How it works

The custom middleware is listening to incoming requests and checks those requests to match npm packages. E.g. a dependency to chart.js will cause a request to resource/chart.js.js. The middleware now derives the module name which is "chart.js" and uses require.resolve("chart.js") to lookup the npm package for it. If an npm package exists, the middleware is using rollup to create a custom AMD bundle for the npm package which uses sap.ui.define instead of define.

The custom task is scanning all AMD dependencies of all modules and tries to resolve the module names. If a module has been found a custom bundle will be created in the proper namespace of the module, e.g. @apollo/client/core will create a custom bundle at dist/resources/@apollo/client/core.js.

How to obtain support

Please use the GitHub bug tracking system to post questions, bug reports or to create pull requests.

Contributing

Any type of contribution (code contributions, pull requests, issues) to this showcase will be equally appreciated.

License

This work is dual-licensed under Apache 2.0 and the Derived Beer-ware License. The official license will be Apache 2.0 but finally you can choose between one of them if you use this work.