Examples and templates for Connectum framework

Framework · Documentation · Quickstart

---

Ready-to-run examples demonstrating Connectum features — from a minimal greeter service to production deployment configs with Docker, Kubernetes, Istio, and Envoy.

Examples

Example	Description	Highlights	Status
basic-service-node	Basic service — Node.js	Direct execution, @connectum/* packages ship compiled JS	Ready
basic-service-bun	Basic service — Bun	Zero-config TypeScript, no loader needed	Ready
basic-service-tsx	Basic service — tsx	Universal TS runner, works on any Node.js 22+	Ready
performance-test-server	k6 benchmarking server	5 parallel servers, interceptor overhead measurement, ports 8080-8084	Ready
extensions/redact	Sensitive data redaction	Proto custom field options, createRedactInterceptor()	Ready
interceptors/jwt	Client-side JWT interceptor	Bearer token injection, createAddTokenInterceptor()	Ready
cross-runtime-test	Cross-runtime compatibility testing	Node.js smoke tests for compiled packages (Bun planned)	Ready
with-custom-interceptor	Echo service with custom interceptors	API key auth, rate limiting	Ready
production-ready	Production deployment bundle	Docker, Compose, K8s, Istio, Envoy	Ready
runn	E2E test suite — runn	Docker-based, 9 runbooks covering all @connectum/* packages, gRPC reflection	Ready
auth	JWT authentication + authorization	Token validation, proto-based authz rules, declarative RBAC	Ready
with-events-nats	EventBus with NATS	Pub/sub events, saga pattern, JetStream	Ready
with-events-kafka	EventBus with Kafka	Event-driven microservices, consumer groups	Ready
with-events-redpanda	EventBus with Redpanda	Saga choreography, custom topics, Redpanda Console	Ready
with-events-valkey	EventBus with Valkey (Redis)	Redis Streams adapter, lightweight event bus	Ready
with-events-amqp	EventBus with RabbitMQ	AMQP adapter, topic exchange, Management UI	Ready
with-events-dlq	EventBus Dead Letter Queue	DLQ service, retry policies, failed event inspection	Ready
o11y-coroot	Observability with Coroot	Distributed tracing, custom metrics, structured logs, service map	Ready

Prerequisites

• Node.js >= 22.13.0, or Bun >= 1.3.6, or tsx >= 4.21 (for TypeScript source in your project)
• pnpm >= 10

Quick Start

git clone https://github.com/Connectum-Framework/examples.git
cd examples/basic-service-node
pnpm install
pnpm dev

The greeter service starts on port 5000 with gRPC Health Check, Server Reflection, and default interceptors enabled.

Test with grpcurl:

grpcurl -plaintext -d '{"name": "World"}' localhost:5000 greeter.v1.GreeterService/SayHello

Production Ready

The production-ready example provides a complete deployment bundle:

• Docker — Multi-stage Dockerfiles (Debian ~200MB, Alpine ~140MB), non-root user, built-in health check
• Docker Compose — Service stack with OpenTelemetry Collector, Jaeger, Prometheus, Grafana
• Kubernetes — Deployment, Service, HPA, RBAC, TLS secrets
• Istio — mTLS, AuthorizationPolicy, canary deployments, header-based routing
• Envoy Gateway — Routing, rate limiting, Swagger UI

See production-ready/README.md for details.

E2E Testing

The runn example provides a comprehensive E2E test suite using runn YAML runbooks:

• 9 runbooks, 30 scenarios covering all @connectum/* packages
• Packages tested: core, healthcheck, reflection, auth, interceptors, otel, events
• Docker Compose — server + runn tests + OpenTelemetry Collector

cd runn
pnpm install && pnpm build:proto
docker compose up --build --exit-code-from tests --abort-on-container-exit

See runn/README.md for details.

Dependencies

All examples use published @connectum/* packages from npm (currently 1.0.0-rc.10). Just pnpm install in any example directory to get started.

License

Apache License 2.0 · Built by Highload.Zone