Open UX Tools

The Open UX tools project aims to provide open source modules that make the development of SAP Fiori applications more efficient. The project is maintained by the same team that is responsible for SAP Fiori tools and driven by the SAP community. The main goal of this project is to collaborate with the community to create transparency and therefore increase the adoption of our tools.

Collaboration: SAP has a great and active development community that is eager to help improve SAP products. With SAP Fiori tools, we have collaborated with stakeholders using roundtables, surveys, and usability testing. We have even collaborated using SAP's incident management systems, connecting with users that did not just report issues but also debugged and identified the root cause. With Open UX tools, we want to take this collaboration to the next level by empowering users to contribute findings, fixes, and improvements to the project.

Transparency: Anyone can inspect the sources, check for inconsistencies or problems, or get inspired to enhance the tools for the SAP Fiori community. Transparency matters to us. It builds trust in our tools and promotes more open communication.

Adoption: The first consumer of these modules is SAP Fiori tools but every module is designed to be reusable by anyone building any kind of tools to develop SAP Fiori applications. This may be other open source projects or internal projects with very specific use cases. With our initial set of modules, we want to enable generator/scaffolding projects to use building blocks to create a common project structure across the SAP ecosystem.

Modules

Our long-term vision is to completely transition our SAP Fiori tools to open source. This is not an easy endeavor due to the size of the code base and dependencies to other not-yet-open-sourced modules. If you would like to better understand how we started and how we are planning to move forward, please have a look at our blog posts History and vision of the Open UX tools and The Open UX Tools Journey Continues.

As a starting point, we have extracted the templates for generating SAP Fiori applications. The templates have been dissected into small but easy to use building blocks that are simple to combine. We then continued adding the most important UI5 tooling middlewares. The repository also contains reusable helper modules e.g. to modify UI5 tooling configuration files.

The image below gives an overview of the currently included modules and their dependencies. It also shows the known consumers of these modules, the SAP Fiori generator (@sap/generator-fiori) and the easyUI5 open source project (generator-easy-ui5).

The repository contains no private modules i.e. all modules are published to npmjs.com under the scope @sap-ux. The name of the published modules (without scope) matches the folder name in packages e.g. ./packages/fiori-freestyle-writer is published as @sap-ux/fiori-freestyle-writer.

Additionally, we have the ./examples folder containing show case implementations using multiple of our modules together.

Requirements

Everything is released as node modules requiring node with a version matching ">=18".

Contributing

Please check the Development Conventions and Guidelines document as well as the Development Setup section in this document.

Development Setup

Local Development

To install pnpm globally using npm, run the following:

npm install -g pnpm

More information on pnpm installation options can be found here.

GitHub Codespaces

To open and develop using GitHub Codespaces:

1. Expand the dropdown '<> Code' button on the open-ux-tools github repository page
2. Select 'Codespaces' tab
3. Press the 'Create codespace on main' button to create a new GitHub Codespace based on the configuration in the file .devcontainer/devcontainer.json

VS Code Development in a Container

To use VS Code and develop in a container:

1. Install docker
2. Install VS Code or VS Code Insiders edition
3. Install the Dev Containers VS Code extension or the Remote Development VS Code extension pack

Open currently opened workspace in dev container using the command Dev Containers: Reopen in Container. This will open a new window using the Dev Containers extension and the configuration in the file .devcontainer/devcontainer.json

Alternatively, you can clone the repository in a container using the command Dev Containers: Clone Repository in Container Volume... and paste the repository URL.

More information on VS Code development in a container can be found here

Install dependencies

To install dependencies and devDependencies, run following command at root of the repository:

pnpm install

Build packages

To transpile the packages, run the following command at the root of the repository or in the individual package:

pnpm build

Format sources using prettier

To format sources, run the following command at the root of the repository or in the individual package:

pnpm format

Run linting of sources using eslint

To run linting of sources, run the following command at the root of the repository or in the individual package:

pnpm lint

To fix linting errors that can be fixed automatically, run the following command at the root of the repository or in the individual package:

pnpm lint:fix

Run unit tests in packages

To run unit tests using jest, run the following command at the root of the repository or in the individual package:

pnpm test

Note: if the test run fails due to dependency issues, run pnpm install && pnpm build in the root of the repository again to make sure all projects are up-to-date.

Debug packages

When analyzing a problem, it is helpful to be able to debug the modules. How to debug them depends on the IDE you are using. In this section, it is described how you could debug with VSCode.

Each of the packages has an extensive set of unit tests covering as many as possible different scenarios, therefore, as a starting point for debugging, it is a good idea to use the tests. The easiest (but not the only) way to debug a specific test in VSCode is to open a JavaScript Debug Terminal and then go to the package that needs to be debugged. Using the debug terminal, execute all tests with pnpm test or a specific one, e.g. execute pnpm test -- test/basic.test.ts in the fiori-freestyle-writer directory (./packages/fiori-freestyle-writer). When running either of the commands in the debug terminal, breakpoints set in VSCode will be active.

Additionally for the *-writer modules it is sometimes helpful to manually inspect the generated output of the unit tests on the filesystem. This can be achieved by setting the variable UX_DEBUG before running the tests e.g. in fiori-freestyle-writer run UX_DEBUG=true pnpm test and after the tests finish, the generated files can be found at ./test/test-output. Additional checks can be performed on the generated projects by also setting UX_DEBUG_FULL e.g. UX_DEBUG=true UX_DEBUG_FULL=true pnpm test. This includes checks such as npm install, npm run ts-typecheck, npm run lint as appropriate to the project.

Create changesets for feature or bug fix branches

A changeset workflow has been setup to version and publish packages to npmjs.com. To create changesets in a feature or bug fix branch, run one of the following commands:

pnpm cset

pnpm changeset

This command brings up an inquirer.js style command line interface with prompts to capture changed packages, bump versions (patch, minor or major) and a message to be included in the changelog files. The changeset configuration files in the .changeset folder at the root need to be committed and pushed to the branch. These files will be used in the GitHub Actions workflow to bump versions and publish the packages.

The general recommendation is to run this changeset command after a feature or bug fix is completed and before creating a pull request.

A GitHub bot changeset-bot has been enabled that adds a comment to pull requests with changeset information from the branch and includes a warning when no changesets are found.

Publish to npmjs.com

All modules are published under the @sap-ux scope. Publishing packages to npmjs.com is done on every merge commit made to the main branch. This is done in two steps in the GitHub Actions workflow:

1. The version job bumps versions of all packages for which changes are detected in the changeset configuration files and also updates changelog files. This job is run when a pull request branch is merged to the main branch and basically runs changeset version and commits and pushes the changes made to the package.json, changelog, and pnpm lock files.

2. The release job is configured to run after the version merge commit has been pushed to the main branch in the version job. This job publishes the changed packages to npmjs.com

Code of Conduct

Everyone participating in this joint project is welcome as long as our Code of Conduct is being adhered to.

Licensing

Copyright (2021) SAP SE and open-ux-tools contributors. Please see our LICENSE for copyright and license information. Detailed information including third-party components and their licensing/copyright information is available via the REUSE tool.