Getting Started

Deploy type-safe Kubernetes infrastructure in 5 minutes. This streamlined guide gets you from zero to running application with minimal setup.

Prerequisites

• Node.js 18+ or Bun installed
• kubectl configured to access a Kubernetes cluster

Don't Have a Cluster?

Use kind, k3s, or any cloud provider's managed Kubernetes service.

Installation

bun add typekro
# or npm install typekro

5-Minute Quick Start

Step 1: Create Your App

Create hello-world.ts:

import { type } from 'arktype';
import { kubernetesComposition } from 'typekro';
import { Deployment, Service, Ingress } from 'typekro/simple';

const AppSpec = type({
  name: 'string',
  image: 'string'
});

export const app = kubernetesComposition(
  {
    name: 'hello-world',
    apiVersion: 'example.com/v1alpha1',
    kind: 'HelloWorld',
    spec: AppSpec,
    status: type({ ready: 'boolean' })
  },
  (spec) => {
    const deployment = Deployment({
      name: spec.name,
      image: spec.image,
      ports: [{ containerPort: 80 }]
    });
    
    const service = Service({
      name: `${spec.name}-service`,
      selector: { app: spec.name },
      ports: [{ port: 80, targetPort: 80 }]
    });

    return {
      // ✨ Natural JavaScript - automatically converted to CEL
      ready: deployment.status.readyReplicas > 0
    };
  }
);

Step 2: Deploy It

Create deploy.ts:

import { app } from './hello-world.js';

const factory = app.factory('direct', { namespace: 'default' });

await factory.deploy({
  name: 'hello-world',
  image: 'nginx:latest'
});

console.log('🚀 Deployed! Check with: kubectl get pods');

Run it:

bun run deploy.ts

Step 3: Verify

kubectl get pods
# Should show: hello-world-xxx Running

🎉 Success! You've deployed your first type-safe Kubernetes app.

What You Just Built

Your simple app demonstrates TypeKro's core concepts:

• 📋 Schema Definition: Type-safe specification using arktype
• 🏗️ Resource Composition: Automatic resource creation and registration
• 🔗 Status Expressions: Dynamic status using CEL expressions
• 🚀 Direct Deployment: Immediate cluster deployment with TypeScript

Advanced Features Preview

TypeKro offers much more power. Here's a taste of what's possible:

Cross-Resource References:

const database = Deployment({ name: 'db', image: 'postgres:15' });
const app = Deployment({
  env: { 
    // ✨ JavaScript template literals work seamlessly
    DATABASE_URL: `postgres://user:pass@${database.status.clusterIP}:5432/mydb`
  }
});

External References Between Compositions:

const webApp = otherComposition.database; // Cross-composition magic!

Conditional Logic:

// ✨ JavaScript conditionals work naturally
const ingress = spec.environment === 'production' 
  ? Ingress({ host: `${spec.name}.example.com` })
  : null;

// Status with JavaScript expressions
return {
  ready: deployment.status.readyReplicas > 0,
  url: ingress ? `https://${spec.name}.example.com` : 'http://localhost'
};

What's Next?

Ready to dive deeper? Follow the Learning Path for a structured progression:

🎯 Recommended Next Steps

1. 📱 Build Your First App - Complete tutorial with realistic patterns
2. 🏭 Master Factory Functions - Learn TypeKro's building blocks
3. ✨ Understand Magic Proxy - TypeKro's reference system
4. 🔗 External References - Connect multiple compositions
5. 🏗️ Advanced Architecture - Deep technical understanding

🚀 Choose Your Path

New to TypeKro? → Start with 📱 First App
Experienced with Kubernetes? → Jump to ✨ Magic Proxy
Building complex systems? → Explore 🔗 External References

📚 More Resources

• Examples - Real-world patterns and complete applications
• API Reference - Complete function and type documentation
• Deployment Guides - GitOps, KRO, and advanced strategies

Quick Help

Issues? Check that kubectl can connect to your cluster:

kubectl cluster-info

Need more help? Open an issue or check our Debugging Guide.