@shepherdjerred/helm-types

Generate TypeScript types from Helm chart values.

What it does

This tool fetches Helm charts and generates strongly-typed TypeScript interfaces from their values.yaml and values.schema.json files. Use it to get type-safe Helm configurations in your TypeScript projects.

Features:

• Fetch charts from any Helm repository
• Generate nested interfaces with proper types
• Parse YAML comments for JSDoc documentation
• Support for arrays, unions, enums, and optional properties
• Handle reserved keywords and special characters

Installation

npm install @shepherdjerred/helm-types
# or
bun add @shepherdjerred/helm-types

Requirements

• Node.js 18+ or Bun
• Helm CLI installed and available in PATH

CLI Usage

Generate types directly with npx/bunx:

# Generate types for ArgoCD
npx @shepherdjerred/helm-types \
  --name argo-cd \
  --repo https://argoproj.github.io/argo-helm \
  --version 8.3.1 \
  --output argo-cd.types.ts

# Short flags
npx @shepherdjerred/helm-types \
  -n argo-cd \
  -r https://argoproj.github.io/argo-helm \
  -v 8.3.1 \
  -o argo-cd.types.ts

# Print to stdout
npx @shepherdjerred/helm-types \
  -n argo-cd \
  -r https://argoproj.github.io/argo-helm \
  -v 8.3.1

# Custom interface name
npx @shepherdjerred/helm-types \
  -n argo-cd \
  -r https://argoproj.github.io/argo-helm \
  -v 8.3.1 \
  -i CustomArgocdValues \
  -o argo-cd.types.ts

Options:

Programmatic API

import {
  fetchHelmChart,
  convertToTypeScriptInterface,
  generateTypeScriptCode,
} from "@shepherdjerred/helm-types";

// 1. Define your chart
const chart = {
  name: "argo-cd",
  chartName: "argo-cd",
  repoUrl: "https://argoproj.github.io/argo-helm",
  version: "8.3.1",
};

// 2. Fetch and generate types
const { values, schema, yamlComments } = await fetchHelmChart(chart);
const tsInterface = convertToTypeScriptInterface(
  values,
  "ArgocdHelmValues",
  schema,
  yamlComments,
);
const code = generateTypeScriptCode(tsInterface, chart.name);

// 3. Write output
await fs.writeFile("argo-cd.types.ts", code);

Generated Output

Values Interface

export type ArgocdHelmValues = {
  /**
   * Number of replicas
   * @default 1
   */
  replicaCount?: number;

  image?: ArgocdHelmValuesImage;
  service?: ArgocdHelmValuesService;
};

Nested Types

export type ArgocdHelmValuesImage = {
  repository?: string;
  tag?: string;
  pullPolicy?: "Always" | "IfNotPresent" | "Never";
};

Parameters Type (Flattened)

A flattened type using dot notation for Helm's --set parameter syntax:

export type ArgocdHelmParameters = {
  replicaCount?: string;
  "image.repository"?: string;
  "image.tag"?: string;
  "service.type"?: string;
};

Type Inference

The library intelligently infers types from values:

JSON schema takes precedence when available.

API Reference

fetchHelmChart(chart: ChartInfo)

Fetches a Helm chart and extracts configuration.

type ChartInfo = {
  name: string; // Unique identifier
  chartName: string; // Chart name in repo
  repoUrl: string; // Helm repository URL
  version: string; // Chart version
};

// Returns
{
  values: Record<string, unknown>;
  schema: JSONSchemaProperty | null;
  yamlComments: Map<string, string>;
}

convertToTypeScriptInterface(values, name, schema?, comments?, prefix?)

Converts Helm values to TypeScript interface definition.

• values - Chart values object
• name - Interface name
• schema? - Optional JSON schema for type hints
• comments? - Optional YAML comments for JSDoc
• prefix? - Optional key prefix for nested types

generateTypeScriptCode(interface, chartName)

Generates TypeScript code from interface definition. Returns a string containing the main values interface, nested type definitions, and flattened parameters type.

parseYAMLComments(yamlContent)

Extracts YAML comments and associates them with keys.

License

GPL-3.0