Cli Simple Chart

CLI Simple Chart

This guide shows how to use the CLI scaffold without treating generated compatibility code as the recommended long-term architecture.

1. Scaffold the project

pnpm exec tl init web

The command creates:

web/
└── chart.ts

The current generator uses object-form manifests and lower-level Helm helpers. That output remains a supported starting point, but new application code should move toward the typed-first library API.

2. Install project dependencies

Inside your project workspace, make sure Timonel and its typed Kubernetes ecosystem are available:

pnpm add timonel cdk8s cdk8s-plus-33 constructs

3. Refactor or extend with typed resources

A maintained chart.ts can use Rutter.getChart() directly:

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

export default function createChart(): Rutter {
  const chart = new Rutter({
    meta: {
      name: 'web',
      version: '1.0.0',
      description: 'Web application',
    },
    defaultValues: {
      environment: 'development',
    },
  });

  const deployment = new kplus.Deployment(chart.getChart(), 'Web', {
    metadata: { name: '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: 'web-config' },
    data: { owner: 'platform' },
  });

  return chart;
}

const chart = createChart();
await chart.write('dist');

If you keep the CLI-generated auto-execution wrapper instead, preserve its expected export and write behavior. The key architectural point is that resources can be native cdk8s-plus constructs.

4. Synthesize through the CLI

From the parent directory:

pnpm exec tl synth web web/dist

The CLI temporarily rewrites the output destination used by the chart and executes the TypeScript entry point with the locally installed tsx runtime.

5. Expected output

A simple typed chart normally looks like:

web/dist/
├── Chart.yaml
├── values.yaml
├── .helmignore
└── templates/
    ├── _helpers.tpl
    ├── Web.yaml
    └── Config.yaml

The resource filenames follow synthesized construct IDs where practical.

6. Validate the chart

helm lint web/dist
helm template web web/dist

Or from inside the generated chart directory:

cd web/dist
pnpm exec tl validate

helm template is useful even when lint passes because it validates how Helm renders the final resource stream.

7. Environment values

Define environment-specific values on Rutter:

const chart = new Rutter({
  meta: { name: 'web', version: '1.0.0' },
  defaultValues: {
    environment: 'development',
  },
  envValues: {
    production: {
      environment: 'production',
    },
  },
});

The generated chart includes:

values.yaml
values-production.yaml

Validate it:

cd web/dist
pnpm exec tl validate --env production

8. Custom resources

When no useful typed construct exists, use object-form addManifest() rather than raw YAML:

chart.addManifest(
  {
    apiVersion: 'example.io/v1',
    kind: 'Widget',
    metadata: { name: 'web-widget' },
    spec: { owner: 'web' },
  },
  'WebWidget',
);

9. Deploy

After reviewing the rendered output:

cd web/dist
pnpm exec tl deploy web web

For production values:

pnpm exec tl deploy web web --env production

Recommended workflow

Use the CLI for:

• initial filesystem scaffolding;
• convenient synthesis;
• local Helm lint/deploy wrappers;
• umbrella project setup.

Use the library for:

• Kubernetes resource definitions;
• values typing;
• chart metadata and values;
• reusable composition;
• policy validation.

That split avoids making the CLI scaffold itself the architecture of your application.