Quick Start

Quick Start

This guide creates and validates a small typed Helm chart without relying on raw YAML.

Prerequisites

• Node.js ^22.22.2, ^24.15.0, or >=26.0.0.
• pnpm 9 or later.
• Helm 3 when you want to lint or render the generated chart.

Install

mkdir timonel-demo
cd timonel-demo
pnpm init
pnpm add timonel cdk8s cdk8s-plus-33 constructs
pnpm add -D typescript tsx @types/node

Set your package to ESM:

{
  "type": "module"
}

Create chart.ts

import * as kplus from 'cdk8s-plus-33';
import { Rutter } from 'timonel';

const chart = new Rutter({
  meta: {
    name: 'demo',
    version: '1.0.0',
    description: 'My first Timonel chart',
  },
  defaultValues: {
    environment: 'development',
  },
  envValues: {
    production: {
      environment: 'production',
    },
  },
});

const deployment = new kplus.Deployment(chart.getChart(), 'Web', {
  metadata: { name: 'demo-web' },
  containers: [
    {
      name: 'web',
      image: 'nginx:1.27',
      portNumber: 80,
      resources: {
        cpu: { request: kplus.Cpu.millis(100) },
      },
    },
  ],
});

deployment.exposeViaService();

new kplus.ConfigMap(chart.getChart(), 'Config', {
  metadata: { name: 'demo-config' },
  data: { owner: 'platform-team' },
});

new kplus.HorizontalPodAutoscaler(chart.getChart(), 'WebHpa', {
  target: deployment,
  minReplicas: 1,
  maxReplicas: 5,
});

await chart.write('./dist/demo');

Run it:

pnpm exec tsx chart.ts

Inspect the output

dist/demo/
├── Chart.yaml
├── values.yaml
├── values-production.yaml
├── .helmignore
└── templates/
    ├── _helpers.tpl
    ├── Web.yaml
    ├── Config.yaml
    └── WebHpa.yaml

The exact set of generated resource filenames follows the logical construct IDs synthesized by cdk8s.

Validate with Helm

helm lint ./dist/demo
helm template demo ./dist/demo
helm template demo ./dist/demo -f ./dist/demo/values-production.yaml

Custom resources

If a resource has no suitable upstream construct, object-form addManifest() is the supported fallback:

chart.addManifest(
  {
    apiVersion: 'example.io/v1',
    kind: 'Widget',
    metadata: { name: 'demo-widget' },
    spec: { size: 'small' },
  },
  'Widget',
);

Do not use the raw YAML overload for new code unless there is no practical typed alternative.

Optional CLI workflow

The CLI can scaffold a project:

pnpm exec tl init demo
pnpm exec tl synth demo demo/dist

The CLI is a convenience layer. For application code, the library API shown above is the preferred starting point.

Next steps

• Architecture
• API Reference
• Type-Safe Helm Helpers
• Best Practices
• Umbrella Chart Examples