docs: TypeScript charts specification #500

kitsunoff · 2025-11-30T22:41:37Z

Summary

Add detailed specification for TypeScript as alternative to Go templates
Define HelmContext API and types
Describe SDK package structure (@nelm/sdk)
Document development and deployment workflow
List CLI commands
Record design decisions

Files

docs/proposals/go-template-alternative/README.md — Overview
docs/proposals/go-template-alternative/api.md — HelmContext API
docs/proposals/go-template-alternative/sdk.md — SDK structure
docs/proposals/go-template-alternative/workflow.md — Workflow
docs/proposals/go-template-alternative/cli.md — CLI commands
docs/proposals/go-template-alternative/decisions.md — Design decisions

Key Decisions

Runtime: quickjs-go (CGO), no WASM
API: render(ctx) → Manifest[] (return-based, not emit)
Context: Everything via ctx (no globals, no imports for runtime)
Subcharts: Full isolation, Nelm orchestrates
SDK: Types only + when() helper, all runtime from Go
Values types: npm script with json-schema-to-typescript

🤖 Generated with Claude Code

Signed-off-by: Ilya Lesikov <[email protected]>

Add detailed specification for TypeScript as Go templates alternative: - HelmContext API and types - SDK package structure - Development and deployment workflow - CLI commands - Design decisions 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

kitsunoff · 2025-12-01T08:38:38Z

should use goja, because it's written in pure go, not cgo bindings
esbuild must be bundled inside nelm cli
for all native functions should use a ctx object in render function

ilya-lesikov · 2025-12-01T09:59:22Z

docs/proposals/go-template-alternative/api.md

+  Files: Files
+
+  // Functions (injected from Go)
+  lookup<T = unknown>(apiVersion: string, kind: string, namespace: string, name: string): T | null


ilya-lesikov · 2025-12-01T10:00:16Z

docs/proposals/go-template-alternative/api.md

+  lookup<T = unknown>(apiVersion: string, kind: string, namespace: string, name: string): T | null
+
+  // Serialization
+  toYaml(obj: unknown): string


all of these functions not needed. Let the user use the libraries he wants

ilya-lesikov · 2025-12-01T10:07:35Z

docs/proposals/go-template-alternative/decisions.md

+
+**Helper for conditionals:**
+```typescript
+import { when } from '@nelm/sdk'


Key changes: - Switch from quickjs-go to goja (pure Go, no CGO) - Add data mechanism for external data fetching - Remove lookup from render phase (deterministic renders) - Remove helper functions (users use npm libraries) - Add esbuild embedded in Nelm notes - Add @nelm/types package structure with K8s types 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

kitsunoff · 2025-12-01T15:53:35Z

I updated my draft
pls review again

ilya-lesikov · 2025-12-02T12:03:42Z

docs/proposals/go-template-alternative/api.md

+## Files
+
+```typescript
+interface Files {


Let's make it

interface File { Name string Data []byte }

We don't really need all these methods, the user can do it himself. And we have all the Data from files already at this point (Helm reads all of them into the memory, even if not used).

ilya-lesikov · 2025-12-02T12:07:51Z

docs/proposals/go-template-alternative/api.md

+  Chart: Chart
+  Capabilities: Capabilities
+  Files: Files
+  Data: D  // Results from data() phase


We'll probably need something like this, but not now.

ilya-lesikov · 2025-12-02T12:09:34Z

docs/proposals/go-template-alternative/api.md

+  ownerReferences?: OwnerReference[]
+  finalizers?: string[]


Suggested change

ownerReferences?: OwnerReference[]

finalizers?: string[]

Not needed

ilya-lesikov · 2025-12-02T12:10:23Z

docs/proposals/go-template-alternative/api.md

+  apiVersion: string
+  kind: string
+  metadata: ObjectMeta
+  [key: string]: unknown


Not sure how can it be done in TS, but this must work for data, spec, or whatever else, or a combination of.

ilya-lesikov · 2025-12-02T12:15:35Z

docs/proposals/go-template-alternative/api.md

+  return condition ? items : []
+}
+
+export default function render(ctx: HelmContext<Values>): Manifest[] {


I'd like to see something like RenderResult here instead of Manifest[].

interface RenderResult { ApiVersion: string // v1 for now Manifests: []Manifest }

ilya-lesikov · 2025-12-02T12:46:00Z

docs/proposals/go-template-alternative/data-mechanism.md

@@ -0,0 +1,367 @@
+# Data Mechanism Proposal


Not interested in this for now.

ilya-lesikov · 2025-12-02T12:46:47Z

docs/proposals/go-template-alternative/decisions.md

+
+```bash
+# Nelm runs internally:
+esbuild src/index.ts --bundle --target=es5 --format=iife --outfile=vendor/bundle.js


Suggested change

esbuild src/index.ts --bundle --target=es5 --format=iife --outfile=vendor/bundle.js

esbuild src/index.ts --bundle --target=es5.1 --format=iife --outfile=vendor/bundle.js

if possible

ilya-lesikov · 2025-12-02T12:49:27Z

docs/proposals/go-template-alternative/sdk.md

+
+| Package | Type | Purpose |
+|---------|------|---------|
+| `@nelm/types` | Types | HelmContext, Manifest, K8s resources |


I'm not into TS/JS, so I don't know how to organize the TS SDK.

ilya-lesikov · 2025-12-02T12:50:10Z

docs/proposals/go-template-alternative/sdk.md

+
+K8s types generated from OpenAPI spec in CI. Version managed in CI pipeline.
+
+## @nelm/crd-to-ts


We can go without it for now. I guess for CRs you can just use any/unknown.

ilya-lesikov · 2025-12-02T12:51:21Z

docs/proposals/go-template-alternative/sdk.md

+  "name": "mychart-ts",
+  "private": true,
+  "scripts": {
+    "generate:values": "json2ts ../values.schema.json -o src/generated/values.types.ts",
+    "generate:crd": "crd-to-ts --crd servicemonitors.monitoring.coreos.com -o src/generated/",
+    "typecheck": "tsc --noEmit",
+    "build": "esbuild src/index.ts --bundle --target=es5 --format=iife --outfile=vendor/bundle.js"
+  },


I don't work with TS/JS, but I just want everything here to be as conventional/standard as possible.

ilya-lesikov · 2025-12-02T12:54:00Z

docs/proposals/go-templates-alternative.md

@@ -0,0 +1,158 @@
+# Feature: Go templates alternative


There is more up-to-date version now, which contains additional details, here:

https://github.com/werf/nelm/pull/497/files

ilya-lesikov and others added 2 commits November 27, 2025 22:22

docs: add Go templates alternative proposal

c616312

Signed-off-by: Ilya Lesikov <[email protected]>

ilya-lesikov reviewed Dec 1, 2025

View reviewed changes

ilya-lesikov reviewed Dec 2, 2025

View reviewed changes

DmitryBochkarev mentioned this pull request Dec 6, 2025

TypeScript based charts definition. Closes #54 #502

Open

11 tasks

	esbuild src/index.ts --bundle --target=es5 --format=iife --outfile=vendor/bundle.js
	esbuild src/index.ts --bundle --target=es5.1 --format=iife --outfile=vendor/bundle.js


		K8s types generated from OpenAPI spec in CI. Version managed in CI pipeline.

		## @nelm/crd-to-ts

docs: TypeScript charts specification #500

Are you sure you want to change the base?

docs: TypeScript charts specification #500

Uh oh!

Conversation

kitsunoff commented Nov 30, 2025

Summary

Files

Key Decisions

Uh oh!

kitsunoff commented Dec 1, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kitsunoff commented Dec 1, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants