Menu
Best practices for developing Cumulocity web applications and components using the Web SDK and Angular. Use when starting a new UI project or creating plugins.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
REST API documentation and guidance for interacting with the Cumulocity AI service. Use when sending messages to the AI agent.
Multi-scope expert for Cumulocity IoT. Accesses live OpenAPI specs for Core API and Digital Twin Manager (DTM).
Setup the local testing environment for Cumulocity applications to test UI and microservices.
Critical implementation patterns for building Cumulocity microservices that act as MCP (Model Context Protocol) servers. Use when developing MCP servers.
Guidelines for developing microfrontends, plugins, and blueprints in Cumulocity, including manifest configuration and package structure. Use when working with microfrontends.
Guidelines for what needs to be ensured if you want to create a new open source repository in the Cumulocity organization.
| name | c8y-websdk |
| description | Best practices for developing Cumulocity web applications and components using the Web SDK and Angular. Use when starting a new UI project or creating plugins. |
You are a web developer, developing UI plugins for Cumulocity.
A full developer guide can be found at https://cumulocity.com/codex/
The Cumulocity Web SDK uses Angular as its main framework and the
Angular tool-set for development. You can get all Web SDK libraries via npm under the @c8y
scope.
Example:
You can add a Cumulocity application to your Angular application by running
the command ng add @c8y/websdk.
Verify that Node.js and npm are correctly installed and the Angular CLI as well. The following table shows an overview of the supported versions:
| Angular version | Web SDK version | Recommended Node.js version |
|---|---|---|
| 20.x.x | 1023.x.x | Node.js 20.x or 22.x |
| 19.x.x | 1022.x.x | Node.js 18.x or 20.x |
| 18.x.x | 1021.x.x | Node.js 18.x or 20.x |
| 17.x.x | 1020.x.x | Node.js 18.x or 20.x |
Important Sandbox Limitation: When generating apps or running
npm installvia the AI agent on macOS, strict sandbox (sandbox-exec) restrictions often causenpm error code EPERM(Operation not permitted) or block write/read access entirely to thenode_modulesand.npmcache directories.The Solution: The AI Agent can scaffold the files (
ng new <app> --skip-install), but you (the user) will often need to open your own terminal and manually run:cd <app_directory> npm install ng add @c8y/websdkThis executes the installation outside the agent's restricted sandbox.
npx --yes @angular/cli@19 new widget-plugin --interactive=false --style=less --ssr=false --skip-install
Navigate to your application's directory:
Wait for the initialization and npm packages installation to complete.
Navigate to your application's directory:
Add the Cumulocity Web SDK to your project:
ng add @c8y/websdk
Confirm the installation of @c8y/websdk.
Select a base project template depending on your goals.
Select a version of the Cumulocity Web SDK to scaffold from. If no furhter instructions select the latest.
Wait for the installation to complete. The Cumulocity Web SDK will be added to your project, including necessary dependencies and configurations.
Info:
When using application templates of administration, cockpit, devicemanagement, and hybrid ensure that Angular always uses non-standalone mode.