TypeScript SDK

The TypeScript SDK lets you define Vorpal build configurations as TypeScript programs. Your config runs with Bun and communicates with the Vorpal daemon over gRPC.

Installation

bun

bun add @altf4llc/vorpal-sdk

npm

npm install @altf4llc/vorpal-sdk

yarn

yarn add @altf4llc/vorpal-sdk

Project setup

Create a Vorpal.toml manifest in your project root:

Vorpal.toml

language = "typescript"

[source]
includes = [
    "bun.lock",
    "package.json",
    "src/vorpal.ts",
    "tsconfig.json"
]

The language field tells Vorpal which SDK to use. The [source] section defines which files to include.

Then create a build configuration in vorpal.ts:

vorpal.ts

import { ConfigContext } from "@altf4llc/vorpal-sdk";

const ctx = ConfigContext.create();

// Define your artifacts here

await ctx.run();

Every Vorpal config starts by creating a context. Target systems are canonical system strings, available as SYSTEMS for every supported platform. The context manages the connection to the Vorpal daemon and tracks all artifacts.

Defining artifacts

Artifacts are the core building blocks in Vorpal. Each artifact defines what to build, which platforms to target, what files to include, and more.

Define an artifact

Use the TypeScript builder to compile a TypeScript project into a cross-platform artifact:

Note

TypeScript is a language-specific abstraction over the generic Artifact type.

vorpal.ts

import { ConfigContext, SYSTEMS, TypeScript } from "@altf4llc/vorpal-sdk";

const ctx = ConfigContext.create();

await new TypeScript("my-app", SYSTEMS)
  .withEntrypoint("src/main.ts")
  .withIncludes(["src", "bun.lock", "package.json", "tsconfig.json"])
  .build(ctx);

await ctx.run();

The TypeScript builder:

• withEntrypoint — Sets the entry file. When set, produces a compiled binary. When omitted, produces a library package.
• withIncludes — Lists files and directories to include in the build source

The TypeScript builder supports additional configuration:

| Method | Description | |--------|-------------| | withEntrypoint(file) | Entry file — binary mode when set, library mode when omitted | | withIncludes(paths) | Source files to include | | withArtifacts(names) | Artifact dependencies available during build | | withEnvironments(vars) | Environment variables for the build | | withSecrets(map) | Build-time secrets | | withAliases(aliases) | Alternative names for the artifact | | withSourceScripts(scripts) | Scripts to run before build | | withWorkingDir(dir) | Custom working directory |

See Artifacts to learn more.

Define artifact dependencies

Build artifacts like Protoc and pass them as dependencies to your language artifact:

Note

Protoc is a built-in artifact provided by the Vorpal SDK. See Built-in artifacts for the full list.

vorpal.ts

import {
  ConfigContext,
  Protoc,
  SYSTEMS,
  TypeScript,
} from "@altf4llc/vorpal-sdk";

const ctx = ConfigContext.create();

const protoc = await new Protoc().build(ctx);

await new TypeScript("my-app", SYSTEMS)
  .withArtifacts([protoc])
  .withEntrypoint("src/main.ts")
  .withIncludes(["src", "bun.lock", "package.json", "tsconfig.json"])
  .build(ctx);

await ctx.run();

The dependent artifact's output is available at $VORPAL_ARTIFACT_<digest> during execution. Use getEnvKey to resolve the path.

See Artifacts to learn more.

Define development environments

Create a portable development shell with pinned tools, environment variables, and more:

vorpal.ts

import {
  ConfigContext,
  Protoc,
  SYSTEMS,
  TypeScriptDevelopmentEnvironment,
} from "@altf4llc/vorpal-sdk";

const ctx = ConfigContext.create();

const protoc = await new Protoc().build(ctx);

await new TypeScriptDevelopmentEnvironment("my-project-shell", SYSTEMS)
  .withArtifacts([protoc])
  .withEnvironments(["NODE_ENV=development", "LOG_LEVEL=debug"])
  .build(ctx);

await ctx.run();

Activate the environment:

Terminal

source $(vorpal build --path my-project-shell)/bin/activate

Verify that dependencies are coming from the Vorpal store:

Terminal

$ which protoc
/var/lib/vorpal/store/artifact/output/library/512b7dd.../bin/protoc

To exit, run deactivate or close the shell.

The development environment builder supports additional configuration:

| Method | Description | |--------|-------------| | withArtifacts(artifacts) | Artifact dependencies available in the shell | | withEnvironments(environments) | Environment variables set in the shell | | withSecrets(secrets) | Secrets available in the shell |

See Environments to learn more.

Define jobs

Jobs run scripts that never cache by default — ideal for CI tasks, tests, and automation.

vorpal.ts

import {
  ConfigContext,
  Job,
  Protoc,
  SYSTEMS,
  TypeScript,
  getEnvKey,
} from "@altf4llc/vorpal-sdk";

const ctx = ConfigContext.create();

const protoc = await new Protoc().build(ctx);

const myApp = await new TypeScript("my-app", SYSTEMS)
  .withArtifacts([protoc])
  .withEntrypoint("src/main.ts")
  .withIncludes(["src", "bun.lock", "package.json", "tsconfig.json"])
  .build(ctx);

const script = `${getEnvKey(myApp)}/bin/my-app --version`;

await new Job("my-job", script, SYSTEMS)
  .withArtifacts([myApp])
  .build(ctx);

await ctx.run();

The Job builder supports additional configuration:

| Method | Description | |--------|-------------| | withArtifacts(artifacts) | Artifact dependencies available during execution | | withSecrets(secrets) | Secrets available during execution |

See Jobs to learn more.

Define processes

Processes wrap long-running binaries with start, stop, and logs lifecycle scripts.

vorpal.ts

import {
  ConfigContext,
  Process,
  Protoc,
  SYSTEMS,
  TypeScript,
  getEnvKey,
} from "@altf4llc/vorpal-sdk";

const ctx = ConfigContext.create();

const protoc = await new Protoc().build(ctx);

const myApp = await new TypeScript("my-app", SYSTEMS)
  .withArtifacts([protoc])
  .withEntrypoint("src/main.ts")
  .withIncludes(["src", "bun.lock", "package.json", "tsconfig.json"])
  .build(ctx);

await new Process(
  "my-server",
  `${getEnvKey(myApp)}/bin/my-server`,
  SYSTEMS,
)
  .withArguments(["--port", "8080"])
  .withArtifacts([myApp])
  .build(ctx);

await ctx.run();

The Process builder supports additional configuration:

| Method | Description | |--------|-------------| | withArguments(args) | Command-line arguments for the process | | withArtifacts(artifacts) | Artifact dependencies available during execution | | withSecrets(secrets) | Secrets available during execution |

See Processes to learn more.

Define user environments

Install tools into your user-wide environment with symlinks:

vorpal.ts

import {
  ConfigContext,
  SYSTEMS,
  TypeScript,
  UserEnvironment,
  getEnvKey,
} from "@altf4llc/vorpal-sdk";

const ctx = ConfigContext.create();

const myApp = await new TypeScript("my-app", SYSTEMS)
  .withEntrypoint("src/main.ts")
  .withIncludes(["src", "bun.lock", "package.json", "tsconfig.json"])
  .build(ctx);

await new UserEnvironment("my-home", SYSTEMS)
  .withArtifacts([myApp])
  .withSymlinks([[`${getEnvKey(myApp)}/bin/my-app`, "$HOME/.vorpal/bin/my-app"]])
  .build(ctx);

await ctx.run();

Activate with $HOME/.vorpal/bin/vorpal-activate, then source $HOME/.vorpal/bin/vorpal-activate-shell.

The UserEnvironment builder supports additional configuration:

| Method | Description | |--------|-------------| | withArtifacts(artifacts) | Artifact dependencies available in the environment | | withEnvironments(environments) | Environment variables set in the environment | | withSymlinks(symlinks) | Symlinks to create from artifact outputs to local paths |

See Environments to learn more.

Custom executors

Replace the default Bash executor with Docker or any custom binary:

vorpal.ts

import {
  ConfigContext,
  Artifact,
  ArtifactStep,
  SYSTEMS,
} from "@altf4llc/vorpal-sdk";

const ctx = ConfigContext.create();

const step = new ArtifactStep("docker")
  .withArguments([
    "run", "--rm", "-v", "$VORPAL_OUTPUT:/out",
    "alpine", "sh", "-lc", "echo hi > /out/hi.txt",
  ])
  .build();

await new Artifact("example-docker", [step], SYSTEMS)
  .build(ctx);

await ctx.run();

The ArtifactStep builder supports additional configuration:

| Method | Description | |--------|-------------| | withArguments(args) | Arguments passed to the entrypoint | | withArtifacts(artifacts) | Artifact dependencies available during execution | | withEnvironments(environments) | Environment variables for the step | | withScript(script) | Script to execute in the step | | withSecrets(secrets) | Secrets available during execution |

The Artifact builder supports additional configuration:

| Method | Description | |--------|-------------| | withAliases(aliases) | Alternative names for the artifact | | withSources(sources) | Source files to include in the artifact |

See Artifacts to learn more.

Building

Run your config with the Vorpal CLI:

vorpal build my-app

First builds download toolchains and dependencies. Subsequent builds with the same inputs resolve instantly from the content-addressed cache.