UI5 TypeScript development just got smoother

[pmuessig]

No more @namespace annotations: ui5-tooling-transpile now auto-detects your UI5 namespace

If you write UI5 with TypeScript, you have almost certainly written this in every controller, control, and component:

/**
 * @namespace ui5.ecosystem.demo.myapp
 */
export default class Main extends Controller {

That annotation exists for one reason: the Babel preset that converts your TypeScript class to a classic sap.ui.define call needs to know which namespace prefix to put in front of controller.Main. Without it, the generated module name comes out wrong and the app breaks at runtime.

Starting with ui5-tooling-transpile 3.14.0, you do not need to write it anymore.

What changed

The new version of babel-preset-transform-ui5 (7.11.0) can derive the namespace from the project structure on its own. ui5-tooling-transpile now reads the namespace and source path configuration from your ui5.yaml, builds the sourceFolders map (a table that says "files under webapp/ belong to this namespace"), and hands it directly to the preset before transpilation starts.

The result is that every file in your project picks up the right namespace prefix automatically. You delete the annotations, and the output is identical to what you had before.

Here is what a controller looks like before and after:

// before
/**
 * @namespace ui5.ecosystem.demo.myapp
 */
export default class Main extends Controller {
  onInit(): void {
    // ...
  }
}

// after
export default class Main extends Controller {
  onInit(): void {
    // ...
  }
}

Same output. One annotation fewer per file. In a medium-sized app with a dozen controllers and a handful of controls, that is a meaningful amount of noise gone.

What it covers

The auto-detection works across all three scenarios you are likely to encounter.

App development. The middleware and the build task both read the project's namespace from ui5.yaml. Files under webapp/ (or whatever path you have configured in resources.configuration.paths.webapp) map to that namespace. Nothing to configure.

Library development. For library projects src/ maps to the project namespace. Same automatic derivation, same zero-config experience.

Middleware with a dependency library. This is the case that was missing before and is the main reason the change landed. When your app runs ui5 serve with ui5-tooling-transpile as middleware, and one of your workspace library dependencies also uses ui5-tooling-transpile, the middleware now walks the dependency graph and registers the sourceFolders of each dependency alongside your own. So if a controller from a local library gets served through the middleware, it resolves to my.lib.controller.Shared instead of src.controller.Shared. No annotations needed in the library either.

External Babel configs. If your project supplies a .babelrc, babel.config.js, or similar, the auto-derived sourceFolders is normally not injected because the external config takes over. Add injectSourceFolders: true to your ui5.yaml configuration block for ui5-tooling-transpile and the preset will receive the derived values, with anything already set in your external config taking precedence:

builder:
  customTasks:
    - name: ui5-tooling-transpile-task
      afterTask: replaceVersion
      configuration:
        injectSourceFolders: true

How to upgrade

Update ui5-tooling-transpile to 3.14.0 or later in your project:

npm install ui5-tooling-transpile@latest --save-dev

Then delete the @namespace JSDoc blocks from your TypeScript source files. That's it. If you use an external Babel config and want to stop writing annotations there too, add injectSourceFolders: true as shown above.

The Easy UI5 TypeScript templates have been updated to match, so new projects generated from those templates will start without annotations from the beginning.

Where to find it

The package is on npm:

👉 https://www.npmjs.com/package/ui5-tooling-transpile

It's part of the ui5-ecosystem-showcase, the collection of UI5 CLI extensions the community uses every day. The showcase itself runs without any @namespace annotations now, so the complete set of app and library scenarios there serves as a working reference.