Starting your journey as a web developer in Cumulocity can be quite overwhelming in the beginning. There are a lot of concepts to discover and sometimes you simply get crushed by the amount of information available in the documentation.
To make your journey easier I have created this tutorial series. This tutorial series targets web developers, who want learn how they can implement custom applications, widgets and plugins for Cumulocity. The various articles of this series will teach fundamental concepts about web development in the context of Cumulocity and point out best practices. As a prerequisite it is assumed that you already have an understanding about Angular and Typescript. Furthermore, you need to have a Cumulocity tenant and also basic knowledge about Cumulocity and its data model.
The tutorial series is divided into multiple articles. Each article focuses on a specific topic accompanied by code samples. These code samples are shared in this public github repository, which allows you to review the code for an individual article. There are a couple of articles planned. This first article discusses general concept about web development in Cumulocity. In addition, you will set up your development environment and create your first custom web application. In the next article you will learn more about how you can extend the custom web application and create your first component. The third article demonstrates how you can use Cumulocity’s API to query data and display it in your web component. This web component will be converted into a Cumulocity widget in the fourth article. You will learn more about extending one of Cumulocity’s default applications as well. In the following articles you will extend this widget and get insight into the upcoming Microfrontend Framework.
Sounds interesting? Then let’s get started!
14.x.x. Installing any later version might cause issues when trying to run or build a Cumulocity web application.
Once you have finished the setup of Node.js you can install the @c8y/cli (command line interface) tool, which is provided by Cumulocity. The
@c8y/cli supports you in creating, building and deploying your Cumulocity plugins and web applications. You can install the command line tools globally by running
npm install -g @c8y/cli
in your command prompt/terminal. This will install the latest official version, which is
1014.0.204 at the time of writing this article. As new versions of Cumulocity are released frequently you also need to update the cli tools regularly to have the latest version. Instead of installing the cli tools globally, I rather recommend to install these on demand using the
npx is part of
npm and allows you to run commands without having the package installed globally first. Furthermore, you can specify which version you want to have installed.
Let’s create an empty custom web application which is based on version
@c8y/cli@next (1016.6.0 at the time of writing):
npx @c8y/cli@next new
Running this command will install the
@c8y/cli locally in a cache and execute the
new command. You will be guided by a wizard to set up your application. The wizard asks you for the name of the application, from which version to scaffold the project from and which template should be used:
You can choose any name, e.g.
my-c8y-application. Select version
latest, in this case
1014.0.x. Use the template
application from which the project should be scaffolded from. The different templates are described in later articles. More information on creating new applications can be found in the official documentation.
Once the Cumulocity project has been generated by the
@c8y/cli, you must install the dependencies. Change directory in the command prompt to your new project and install all necessary dependencies:
cd my-c8y-application npm install
Once the installation is finished, you can start the Cumulocity web application:
npx c8ycli server -u <<C8Y-URL>>
Make sure to replace
<<C8Y-URL>> with the URL of your Cumulocity instance. The
server command will spin up a local web server and deploy the Cumulocity web application. The
-u parameter specifies the Cumulocity instance to which all API requests should be proxied to. This means data is actually pulled from the configured Cumulocity instance. The same applies for the authentication. The application can be accessed in the browser via the URL:
http://localhost:9000/apps/my-c8y-application/. In case you choose a different application name, you will see your application name instead of
my-c8y-application in the URL.
You will be greeted by the login screen.
Provide the tenant id and user credentials of you configured Cumulocity instance. The tenant id can be found in your configured Cumulocity tenant by clicking on your user at the top right of the header:
When you successfully signed in to your local Cumulocity instance, you will see a blank application:
Great, you have set up your development environment and created your first Cumulocity web application. In the next articles, you will create plugins and widgets to bring some life to your web application. To stop your application, you can simply enter
[CTRL] + [C] inside the terminal.
That’s it for part 1 of this tutorial series. You can find the sample application in the github repository. In part 2 you will extend the empty application with a custom component. Furthermore, you will get to know some tips and best practices about c8y web development. If you like you can leave a comment if you want to see a specific topic to be covered in this tutorial series.