Examples

Explore real-world TypeKro applications with complete, runnable code. Each example demonstrates the imperative composition pattern using kubernetesComposition and showcases TypeKro's unique capabilities.

🎯 Essential Examples (Start Here)

Master TypeKro progressively through our curated essential examples, each building on the previous concepts.

1. Basic WebApp 🎓 (Start Here)

Your first TypeKro application - deployment + service using imperative composition.

Learn: kubernetesComposition basics, factory functions, schema references, status derivation

2. Database Integration 🗄️

Full-stack web application with PostgreSQL database and cross-resource references.

Learn: Multi-resource coordination, service discovery, environment configuration, resource dependencies

3. Microservices 🔄

Multi-service application with API gateway, demonstrating service coordination patterns.

Learn: Service mesh integration, complex routing, distributed status aggregation

4. Multi-Environment 🌍

Single codebase deployed across dev/staging/production with environment-specific configuration.

Learn: Environment parametrization, resource scaling, GitOps workflows, deployment strategies

5. Monitoring Stack 📊

Comprehensive observability with Prometheus, Grafana, and custom metrics.

Learn: Infrastructure monitoring, custom metrics, alerting, operational patterns

6. JavaScript Expressions ⚡ (New Feature)

Comprehensive example of TypeKro's automatic JavaScript-to-CEL conversion system.

Learn: Natural JavaScript syntax, automatic CEL conversion, performance optimization, migration patterns

🚀 TypeKro's Unique Capabilities

These examples showcase features that make TypeKro special compared to other infrastructure tools.

JavaScript to CEL Conversion

TypeKro automatically converts JavaScript expressions to CEL when they contain resource references:

// Write natural JavaScript - TypeKro converts to CEL automatically
(schema, resources) => ({
  ready: resources.deployment.status.readyReplicas > 0,
  url: `https://${resources.service.status.clusterIP}`,
  phase: resources.deployment.status.readyReplicas === schema.spec.replicas ? 'ready' : 'scaling'
})

Demonstrated in: JavaScript Expressions

Magic Proxy System & Schema References

See how TypeKro's magic proxy automatically converts schema references to CEL expressions at runtime:

const app = kubernetesComposition({
  name: 'webapp', 
  apiVersion: 'example.com/v1',
  kind: 'WebApp',
  spec: type({ name: 'string', replicas: 'number' })
}, (schema) => {
  const deployment = Deployment({
    name: schema.spec.name,        // ← Becomes CEL expression
    replicas: schema.spec.replicas // ← Type-safe at compile-time
  });
  
  return { deployment };
});

External References & Cross-Composition

Learn how to reference resources from other compositions using externalRef():

// Reference database from separate composition
const dbRef = externalRef('database', 'my-database');
const app = kubernetesComposition(definition, (schema) => {
  const deployment = Deployment({
    env: {
      DATABASE_URL: `postgres://${dbRef.service.spec.clusterIP}:5432/app` // ✨ Natural JavaScript template literal
    }
  });
  return { deployment };
});

Demonstrated in: Database Integration, Microservices

Runtime Status Intelligence

TypeKro automatically derives meaningful status from your resources:

// Status automatically computed from deployment health
return { 
  ready: deployment.status.readyReplicas > 0,  // ✨ Natural JavaScript - automatically converted to CEL
  url: `https://${ingress.status.loadBalancer.ingress[0].hostname}` // ✨ Natural JavaScript template literal
};

📚 Learning Path by Experience

🟢 New to TypeKro?

Follow this path to master TypeKro systematically:

1. Basic WebApp - Learn imperative composition fundamentals
2. Database Integration - Add cross-resource dependencies
3. Multi-Environment - Scale across environments

🟡 Kubernetes Experience?

Skip basics and focus on TypeKro's unique features:

1. Microservices - Complex service coordination
2. Monitoring Stack - Operational excellence

🔵 Infrastructure as Code Background?

Compare TypeKro with your current tools:

• vs Pulumi: See Basic WebApp for type-safety comparison
• vs CDK8s: See Database Integration for runtime intelligence
• vs Helm: See Multi-Environment for deterministic YAML
• vs Kustomize: See Multi-Environment for programmatic flexibility

🎯 Choose Your Path

I want to build...

• Web Applications: Start with Basic WebApp → Database Integration
• API Services: Database Integration → Microservices
• Production Infrastructure: Multi-Environment → Monitoring
• Observability: Monitoring Stack

I want to learn...

• TypeKro Basics: Basic WebApp
• Resource Dependencies: Database Integration
• Complex Orchestration: Microservices
• GitOps Workflows: See GitOps Guide
• Production Patterns: Multi-Environment + Monitoring

🏃‍♂️ Running the Examples

Every example is complete and runnable with copy-paste code using the kubernetesComposition API.

What's Included

✅ Complete source code - Copy and run immediately
✅ Step-by-step setup - From installation to deployment
✅ Key concepts explained - Why each pattern matters
✅ Production variations - Real-world adaptations

Prerequisites

# Runtime
node >= 18 || bun >= 1.0

# Kubernetes cluster (any of):
minikube start              # Local development
kind create cluster         # Docker-based
# Or use existing cluster

# Install TypeKro
bun add typekro
# or
npm install typekro

Quick Start Any Example

# 1. Copy the example code from any guide
# 2. Save as app.ts
# 3. Run directly
bun run app.ts

# Or deploy to cluster
kubectl apply -f <generated-yaml>

Deployment Options

Each example works with both deployment strategies:

// Direct deployment (immediate)
await app.factory('direct').deploy(spec);

// GitOps YAML generation  
const yaml = app.factory('kro').toYaml(spec);
writeFileSync('k8s/app.yaml', yaml);

📈 From Examples to Production

Our examples show realistic patterns you'll actually use:

• Development: Direct deployment for fast iteration
• Staging: GitOps YAML with environment-specific config
• Production: Full CI/CD with monitoring and observability

Next Steps After Examples

1. API Reference - Complete function documentation
2. Deployment Strategies - Choose the right approach
3. Custom Factories - Build reusable components

🤝 Community & Support

Contributing Examples

Share your TypeKro patterns with the community:

1. Real-world use cases using kubernetesComposition
2. Clear documentation with working code
3. Submit via GitHub Issues or Discussions

Getting Help

• Quick Questions: Discord Community
• Detailed Discussions: GitHub Discussions
• Bug Reports: GitHub Issues

---

Ready to start? Begin with Basic WebApp to learn TypeKro's imperative composition fundamentals! 🚀