Getting Ready for UI5 Development with Visual Studio Code

 In this blog post, I’d like to share my experience with the process of preparing my local development environment for the development of UI5 applications – including required installations, useful additions, and lessons learned while configuring my machine to quick-start UI5 development with Visual Studio Code (VS Code).

As a dual-student in SAP’s Vocational Training Program, I can experience various technologies as part of my internships at different teams within the organization. Therefore, I often find myself setting up new development environments and figuring out the quirks of the recommended or my self-chosen tools along the way. My personal work circumstances aside, as fellow developers, we’re naturally always eager to try new things. Unfortunately, this includes missing some steps in the setup process from time to time while trying to get to the fun part as soon as possible – I’m sure we can all relate to that!

So here I’ll now share how I recently configured my local development environment for UI5 with VS Code on Windows. The following steps include everything to quick-start UI5 development:

• Step 1 – Prerequisites: Node.js, SAPUI5 CLI, and Git
• Step 2 – Main mission: VS Code, UI5 Extensions, and Code Completion
• Step 3 – Touch-ups: UI5 Generator options and DevTools Browser Extension

Update 26th Oct 2021: Additions regarding JavaScript code assist libraries

Prerequisites: Node.js, SAPUI5 CLI, and Git

The Node.js JavaScript runtime is needed for some of the tools involved in developing UI5 applications.

Opening up a terminal of your choice and executing the following command will show the currently installed Node.js version:

node --version

If this returns no version at all, or like in my case, a version, which is not consistent with the latest long-term support, the installer to get the latest LTS version (currently v16.x.x) is available here: download Node.js. This step is essential to prevent potential incompatibility issues later in the configuration process since other tools may require a certain version of Node.js.

Learn more about Node.js and the Node Packet Manager (npm): What is Node.js? – nodejs.org What is npm? – nodejs.org npm documentation – npmjs.com

To develop UI5 applications, UI5 Tooling in terms of the UI5 CLI is required. It can be installed via the npm packet manager with this command:

npm install --global @ui5/cli

The successful installation can be verified with the version command:

ui5 --version

 

Learn more about UI5 Tooling and the UI5 Command Line Interface (CLI): What is UI5 Tooling? – sap.github.io/ui5-tooling UI5 Command Line Interface – sap.github.io/ui5-tooling @ui5/cli package – npmjs.com ui5-cli – github.com

For collaborations, cloning sample repositories, and similar scenarios, my development environment always includes Git and the Git Bash, which is part of the Git for Windows installation. Git version control can be utilized from the command line, via the GUI in VS Code itself, or from many other dedicated tools. However, this is technically an optional step.

The Git installation can be verified with this command:

git --version

And Git itself can be downloaded from here if needed: download Git.

Learn more about Git and Git in Visual Studio Code: Download Git – git-scm.com What is Git? – git-scm.com VS Code version control Git support – code.visualstudio.com

Main mission: VS Code, UI5 Extensions, and Code Completion

With these prerequisites out of the way, it’s finally time to get to the main task of this setup process: VS Code and extensions for UI5 development.

Visual Studio Code is one of the recommended code editors for UI5 development and offers features like:

• IntelliSense for smart completions
• Integrated debugging
• Built-in Git
• Extensibility and customization via extensions

The latest version for the corresponding operating systems can be downloaded from here: download Visual Studio Code.

Learn more about the Visual Studio Code code editor: What is Visual Studio Code? – code.visualstudio.com Download Visual Studio Code – code.visualstudio.com VS Code Extension Marketplace – code.visualstudio.com

After successfully installing VS Code, there are multiple extensions to facilitate UI5 development that we can add to the code editor. SAP provides a convenient VS Code extension pack for UI5 development – the SAP Fiori tools Extension Pack. It bundles the most important extensions for UI5 and SAP Fiori development.

It can be installed by choosing the Extension Marketplace in the tab bar on the left side (or Ctrl+Shift+X) and searching for ‘SAP Fiori tools’. After selecting ‘install’, the extensions are enabled automatically. It might be required to reload VS Code to enable specific extensions, be sure to do this if necessary before continuing with the setup.

Extension Marketplace in VS Code

SAP Fiori tools – Extension Pack

After installing the extension pack VS Code supports UI5 development with these extensions:

• SAP Fiori tools – Application Modeler
• SAP Fiori tools – Guided Development
• SAP Fiori tools – Service Modeler
• SAP Fiori tools – XML  Annotation Language Server
• Application Wizard (UX for Yeoman generators)
• XML Toolkit (Language support for XML)

In addition to the extensions listed above, I’d like to recommend the UI5 Language Assistant. While some of the extensions from the SAP Fiori extensions pack also support dealing with XML files for views, fragments, and so on, this one proved to be especially valuable for me. It significantly improves code completion and formatting for XML. Combined with the XML Annotation Language Server and the XML Toolkit, VS Code now provides a powerful toolset for all things XML within UI5 projects. The UI5 Language Assistant can be easily installed from the Marketplace too.

UI5 Language Assistant Extension

Learn more about these UI5 Visual Studio Code extensions: SAPSE.sap-ux-fiori-tools-extension-pack – marketplace.visualstudio.com SAPOS.yeoman-ui – marketplace.visualstudio.com SAPSE.sap-ux-application-modeler-extension – marketplace.visualstudio.com SAPSE.sap-ux-help-extension – marketplace.visualstudio.com SAPSE.sap-ux-service-modeler-extension – marketplace.visualstudio.com SAPSE.sap-ux-annotation-modeler-extension – marketplace.visualstudio.com SAPOSS.xml-toolkit – marketplace.visualstudio.com SAPOSS.vscode-ui5-language-assistant – marketplace.visualstudio.com iljapostnovs.ui5plugin – marketplace.visualstudio.com

Alright, but what about JavaScript? Can we support development in JavaScript files with additional tools as well? Unfortunately, the answer to that is a little more complicated. Some community extensions on the VS Code Extension Marketplace try to offer JavaScript support for UI5 development. ‘SAPUI5 Extension‘ is an honorable mention here. However, I was not entirely satisfied with the features these tools offered. So I started looking for different options to have code completion for JavaScript coding in my UI5 projects.

One way to get code assistance is utilizing some of TypeScript’s features without actually using TypeScript itself. It might sound a little confusing, but UI5 types for TypeScript combined with JSDoc can help with error detection and code completion. Here is how to implement JavaScript code assistance in a UI5 project. Note: This approach is not a general VS Code personalization step. It refers to configurations inside a specific UI5 project!

There is an alternative to this manual procedure. In the next section of this post, we’ll look at different UI5 generator options to simplify the development process. Among other things, they also offer ways to add the required configuration for javascript code assistance to a project in a more convenient manner. So lots of ways to get to the desired outcome – for now, let’s continue with the manual configuration.

The additional packages ‘eslint‘, ‘@sap/eslint-plugin-ui5-jsdocs‘, and ‘@sapui5/ts-types‘ need to be installed and added to the project’s devDependencies. For this, we can run the following npm command:

npm install --save-dev eslint @sap/eslint-plugin-ui5-jsdocs @sapui5/ts-types

In the next step, adding a ‘tsconfig.json’ file to the project’s root folder is necessary to make VS Code aware that we want to use the UI5 types. The file should look like this:

{
    "compilerOptions": {
        "module": "none",
        "noEmit": true,
        "checkJs": true,
        "allowJs": true,
        "types": [
            "@sapui5/ts-types"
        ]
    }
}

Afterward, ESLint needs to know about the ‘ui5-jsdocs’-plugin package. Therefore we add a ‘.eslintrc’ file with this content to the root folder of our project. If the project already uses ESLint, these additional lines can simply be added at the end of the current configuration file.

{
	"plugins": [
		"@sap/ui5-jsdocs"
	],
	"extends": [
		"plugin:@sap/ui5-jsdocs/recommended",
		"eslint:recommended"
	]
}

 

Learn more about TypeScript (with UI5), JSDoc, and ESLint: What is TypeScript? – typescriptlang.org What is a tsconfig.json? – typescriptlang.org ui5-typescript – github.com Getting Started with TypeScript for UI5 Application Development – blogs.sap.com Add JavaScript Code Assist – SAP Help Portal @sapui5/ts-types package – npmjs.com What is JSDoc? – jsdoc.app TypeScript JSDoc Reference – typescriptlang.org What is ESLint? – eslint.org eslint package – npmjs.com @sap/eslint-plugin-ui5-jsdocs package – npmjs.com

Now, code assistance for UI5 is ready. Jump to any JavaScript file to test the new feature. However, there are some downsides to this approach too. It’s not possible to configure this in VS Code itself. Instead, these steps must be repeated for every UI5 project to use code assistance via TypeScript types. Moreover, this solution also relies on the developer to add JSDoc annotations where it’s otherwise unclear which type a parameter or variable is referring to. The good news is that VS Code helps add those annotations because we installed the ‘ui5-jsdocs’ plugin. Here is an example of how to use JSDoc in this context:

Quick-Fix missing JSDoc problem

Enabled code completion after JSDoc addition

When deciding between the different options for code assistance in UI5 JavaScript files, it comes down to personal preference if using a VS Code extension or abusing one of TypeScript’s advantages works better. For now, I prefer working with the TypeScript types, even though a bit more effort is required for this approach.

Touch-ups: UI5 Generator options and DevTools Browser Extension

At this point, the main work is done, and VS Code is ready for UI5 development. However, using one of the UI5 generator options significantly helps to quick-start and simplify the development process. In VS Code, we can use the SAP Fiori Application Generator, which we just installed along with the extension pack, to generate template SAP Fiori elements or Freestyle SAPUI5 applications.

Opening VS Code’s command palette with View -> Command Palette.. (or Ctrl+Shift+P) and choosing ‘Fiori: Open Application Generator’ provokes the Template Wizard to generate UI5 applications from a template (Note that when accessing this for the first time, the ‘@sap/generator-fiori‘ is installed automatically for this purpose). From here, it’s possible to choose one of the provided floorplans and follow the wizard’s steps to get started.

Application Generator from the command palette

Template Wizard SAP Fiori elements and SAPUI5 Freestyle floorplan options

As already mentioned above, UI5 generators can also add JavaScript code assistance to a project. For this, we just need to select ‘Yes’ for ‘Configure advanced options’ followed by ‘Add javascript code assist libraries to your project.’ No further manual configuration is required for code completion to be available within the generated project.

Template Wizard advanced options – JavaScript code assist libraries

Another option to quick-start UI5 development, which I found particularly useful, is the Yeoman Easy-Ui5 generator tool. This generator is provoked from the command line and offers some handy templates and configuration options. To use the generator, Yeoman needs to be installed. This can be verified once again with the version command:

yo --version

If yo is not recognized, Yeoman can be installed with this simple npm command:

npm install --global yo

Now the actual easy-ui5-generator can be added by running the following npm install command:

npm install --global generator-easy-ui5

And afterward, the installation can be verified by starting Yeoman and looking for ‘Easy-Ui5’ in the list of generators:

yo

List of available Yeoman generators including Easy-Ui5

The Easy-Ui5 generator provides numerous options to help develop a UI5 project, such as creating a new project, adding a new model, or a new view to an existing project.

Easy-Ui5 generator options

While creating a new project, the generator asks if JavaScript code assistance should be added. Choosing ‘Yes’, will configure JavaScript code completion similar to the manual approach with TypeScript types from above. After successful creation, it is available right away.

UI5 project generator JavaScript code assist libraries option

Learn more about Yeoman and UI5 generators: Develop SAP Fiori Applications with SAP Fiori tools – SAP Help Portal What is Yeoman? – yeoman.io @sap/generator-fiori package – npmjs.com generator-easy-ui5 – github.com generator-easy-ui5 package – www.npmjs.com Easy-UI5 3.0 – From Community Contributions to Community Plugins – blogs.sap.com

One other tool has to be mentioned when discussing UI5 development – the UI5 Inspector Chrome browser extension. UI5 Inspector helps with inspecting, analyzing, and debugging UI5-based applications in Chrome. For that purpose, it adds a new section to Chrome’s integrated DevTools (F12). I wouldn’t want to miss this helpful extension in my development process. The browser extension can be downloaded from the Chrome Web Store here: download UI5 Inspector.

UI5 Inspector in Chrome DevTools

Learn more about the UI5 Inspector Chrome browser extension: SAPUI5 SDK Documentation UI5 Inspector – sapui5.hana.ondemand.com Chrome Web Store UI5 Inspector – chrome.google.com

Wrap-up

Done! Those were all the initial steps I took to set up my local development environment for UI5 with VS Code. Now it’s time for the fun part – starting to build some UI5 applications. Of course, there are always more things to add to fine-tune one’s development setup. So, let me know about your must-have additions for local UI5 development in VS Code.

Src: https://blogs.sap.com/2021/10/15/getting-ready-for-ui5-development-with-visual-studio-code/