Introducing c8y-nitro: Modern JavaScript for Cumulocity Microservices

Forum
, , ,
1

Introducing c8y-nitro: Modern JavaScript for Cumulocity Microservices

I’m excited to share c8y-nitro, a new framework for building Cumulocity IoT microservices with modern JavaScript and TypeScript. Built on the powerful Nitro v3 engine, it brings a fresh approach to microservice development with an emphasis on developer experience and productivity.

Why Modern JavaScript?

JavaScript has evolved dramatically over the past few years. With TypeScript, modern runtimes, and frameworks like Nitro, server-side JavaScript development now offers enterprise-grade performance, excellent type safety, and a development experience that’s hard to beat. c8y-nitro harnesses these advancements to make Cumulocity microservice development faster and more enjoyable.

What Makes c8y-nitro Different?

Zero-Configuration Development
The framework handles the entire development setup automatically. Run pnpm dev and it will:

  • Check if your microservice exists on the tenant
  • Create and subscribe it if needed
  • Retrieve and securely save bootstrap credentials
  • Start a development server with hot module reload

No manual credential management. No copying Base64 strings from browser DevTools. Just code.

Automatic Microservice Packaging
When you run pnpm build, c8y-nitro automatically:

  • Generates an optimized Dockerfile
  • Builds the Docker image
  • Creates the cumulocity.json manifest from your package.json
  • Packages everything into a deployment-ready zip file

The zip file is ready to upload directly to your tenant—no additional build scripts or configuration needed.

Built-in CLI for Tenant Management
c8y-nitro includes a CLI that streamlines common tasks:

  • c8y-nitro bootstrap - Manually register and update your microservice
  • c8y-nitro roles - Interactively manage custom roles for your development user

These commands integrate seamlessly with your .env file, maintaining a consistent configuration across your entire workflow.

File-Based Routing
Routes are automatically discovered from your file structure. Create server/routes/api/users.get.ts and you instantly have a GET endpoint at /api/users. The framework handles all the routing configuration, letting you focus on implementing features.

TypeScript Throughout
Full type safety from routes to API clients. Your manifest’s custom roles are automatically available as TypeScript types in middleware and runtime code. Route parameters, request bodies, and responses are all fully typed with excellent IDE autocompletion.

API Client Generation
For monorepo architectures, c8y-nitro can generate TypeScript Angular services that provide fully typed access to your microservice routes—perfect for web application development alongside your microservice.

Rich Utility Library
The framework includes utilities for common Cumulocity tasks:

  • User authentication and authorization middleware
  • Tenant credential management with intelligent caching
  • Pre-configured API clients for different authentication contexts
  • Built-in liveness and readiness probes

Getting Started in Seconds

The fastest way to start is with the c8y-nitro-starter template:

pnpm dlx giget@latest gh:schplitt/c8y-nitro-starter my-microservice
cd my-microservice
pnpm install

Configure your .env file with your development tenant credentials:

C8Y_BASEURL=https://your-tenant.cumulocity.com
C8Y_DEVELOPMENT_TENANT=t12345
C8Y_DEVELOPMENT_USER=your-username
C8Y_DEVELOPMENT_PASSWORD=your-password

Then simply:

pnpm dev

That’s it! Your microservice is running locally with hot reload, automatically registered on your tenant, and ready for development.

Example: A Simple API Endpoint

Create server/routes/api/devices.get.ts:

import { useUserClient } from 'c8y-nitro/utils'

export default defineEventHandler(async (event) => {
  const client = useUserClient(event)
  const { data: devices } = await client.inventory.list()
  return devices
})

Visit http://localhost:3000/api/devices and you’ll see your tenant’s devices—fully authenticated and ready to go.

Important Note: Early Alpha Status

Both Nitro v3 and c8y-nitro are currently in early alpha. While the framework is functional and actively developed, expect changes and improvements as both projects mature. I’m building in public and welcome feedback from the community.

What’s Next?

I’m actively developing c8y-nitro with a focus on:

  • Additional developer utilities and middleware
  • Enhanced debugging capabilities
  • Better integration with Cumulocity’s ecosystem
  • Comprehensive documentation and examples

The framework is open-source (MIT) and available on GitHub.

Feedback is very welcome! Whether you have ideas for new features, suggestions for improvements, or just want to share your experience, I’d love to hear from you. Feel free to open issues, start discussions, or contribute directly to the repository.

If you’re building Cumulocity microservices and want to experience modern JavaScript development, give c8y-nitro a try. The development experience might surprise you!

5 Likes