synth

README

go-synth

A Go library to dynamically synth Constructs.

Given a CDKTF App "entry" script, return synthesized output.

BunExecutor

[!WARNING] Bun binary is expected on PATH

Example usage (see cmd/main.go)

logger := zap.NewProduction()
app := synth.NewApp(executors.NewBunExecutor, logger)
app.Configure(ctx, models.AppConfig{
    Dependencies: map[string]string{
      "my-cdktf-pkg": "0.0.1",
    },
    ScopedPackages: []models.ScopedPackageOptions{},
})
// prepare afero fs to receive the result
dstFs := afero.NewOsFs()

mainTs := `import { App } from "cdktf";
import { MyStack, MyResource } from "my-cdktf-pkg";

const outdir = "cdktf.out";
const app = new App({
  outdir,
});
const stack = new MyStack(app, "my-stack", {
  address: "http://localhost:1234",
});
new MyResource(stack, "my-resource");

app.synth();`

// Execute the main.ts script and copy the synthesized stack out
if err = app.Eval(ctx, dstFs, string(mainTs), *srcDir, *outDir); err != nil {
  logger.Fatal("Failed to execute main.ts script", zap.Error(err))
}

NodeExecutor

[!WARNING] Requires valid NodeJS and package manager (default: pnpm) on $PATH

Example usage (see executors/node_executor_test.go)

logger := zap.NewProduction()
app := synth.NewApp(executors.NewNodeExecutor, logger)
app.Configure(ctx, models.AppConfig{
    Dependencies: map[string]string{
      "my-cdktf-pkg": "0.0.1",
    },
    DevDependencies: map[string]string{
      "@swc/core":  "^1.7.6", // swc is included by default
    },
    ExecutorOptions: map[string]string{
      // entrypoint setup (install) and eval (run)
      "entrypoint": "pnpm",
      // script ran by pnpm to synth main.ts
      "synthScript": "ts-node --swc -P ./tsconfig.json main.ts",
    },
})
// prepare afero fs to receive the result
destFs := afero.NewOsFs()

mainTs := `import { App } from "cdktf";
import { MyStack, MyResource } from "my-cdktf-pkg";

const outdir = "cdktf.out";
const app = new App({
  outdir,
});
const stack = new MyStack(app, "my-stack", {
  address: "http://localhost:1234",
});
new MyResource(stack, "my-resource");

app.synth();`

// Execute the main.ts script and copy the synthesized stack out
if err = app.Eval(ctx, dstFs, string(mainTs), *srcDir, *outDir); err != nil {
  logger.Fatal("Failed to execute main.ts script", zap.Error(err))
}

FAQ

JSII supports Golang, what is this?

While it is true Constructs may be written in Golang or TS Constructs can be cross-compiled to Golang using JSII, dynamically loading these libraries and executing them is not possible.

go-synth addresses this by allowing you to dynamically generate the CDKTF app and synthesize it.

Why doesn't it work on my machine?

This library has currently only been manually test on Linux (WSL) with Bun 1.1.23, NodeJS v20 and pnpm v9.

Feel free to open a ticket until CI/CD has been configured.

Todo

• Add Bun Executor
• Add Node+Pnpm Executor
• Add LICENSE
• Add CI/CD and Release process
• Add golang executor (use JSII cross compiled CDKTF Golang constructs with go run)
• Add go-typescript executor (goja/#519(comment) / go-typescript/pull/13)

Add benchmarking across executors.

Documentation

Index

• type App
  • func NewApp(newFn models.NewExecutorFn, logger *zap.Logger) App

Types

type App

type App interface {
	// Configure is a one time set up for the App environment reused by each Eval call.
	//
	// Configure is meant to handle Auth configuration and other setup that is shared across multiple Eval calls.
	Configure(ctx context.Context, config models.AppConfig) error
	// Eval runs the provided main.ts script in the App environment.
	//
	// Once the script has run, the contents of the src directory are
	// copied to the dest directory into the provided fs.
	//
	// Each call to Eval is independent.
	Eval(ctx context.Context, fs afero.Fs, mainTs, src, dest string) error
}

App defines the interface for managing the synthesis process.

func NewApp

func NewApp(newFn models.NewExecutorFn, logger *zap.Logger) App