Home

Timonel

Timonel is a TypeScript library for generating Helm charts programmatically on top of cdk8s, cdk8s-plus-33, and constructs.

The library API is the primary product. The tl command is a secondary convenience layer for scaffolding, synthesis, validation, and deployment.

Design principles

Timonel follows a typed-first resource model:

1. Prefer cdk8s-plus-33 constructs when an appropriate construct exists.
2. Use a typed cdk8s ApiObject when a higher-level construct is unavailable.
3. Use a focused Timonel abstraction for recurring Kubernetes or Helm patterns.
4. Treat raw YAML as a legacy escape hatch.

This keeps Kubernetes structure in TypeScript while Timonel handles Helm chart assembly, Helm-aware serialization, values files, helper templates, and optional policy validation.

Install

pnpm add timonel cdk8s cdk8s-plus-33 constructs

Supported Node.js ranges are:

^22.22.2 || ^24.15.0 || >=26.0.0

First chart

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

const chart = new Rutter({
  meta: {
    name: 'web-app',
    version: '1.0.0',
    description: 'Typed web application chart',
  },
});

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

deployment.exposeViaService();

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

await chart.write('./dist/web-app');

Timonel writes a Helm chart containing Chart.yaml, values.yaml, .helmignore, templates/_helpers.tpl, and deterministic template files for synthesized resources.

What to read next

• Quick Start for a complete first-chart workflow.
• Architecture for the resource and synthesis model.
• API Reference for the supported public surface.
• Type-Safe Helm Helpers for valuesRef<T>().
• Production Typed-Only Migration for strict migrations that forbid raw manifest fallbacks and casts.
• Umbrella Chart Examples for multi-chart applications.
• Policy Engine for optional manifest validation.
• CLI Reference when you want the command-line convenience layer.

Raw YAML status

The raw-string overload of Rutter.addManifest() and Rutter.addTemplateManifest() are deprecated. New examples should not use them when the same resource can be represented with a typed construct or object.

addManifest(object, id) remains an escape hatch for CRDs and custom resources that do not have a suitable upstream typed construct.

Releases

Timonel uses a main-based trunk flow. Successful main CI runs can publish a canary package. Stable releases are explicit and run through the protected npm production environment.

See Release and Versioning for details.