TypeScript Quickstart

Overview

Orvanta supports TypeScript scripts using Bun, Node.js, and Deno as available runtimes. Scripts consist of code and settings, with the main function serving as the entrypoint.

Scripts structure

Scripts require two components:

1. Code: Must include a main function as the entrypoint.
2. Settings: Metadata including path, summary, description, and JSON Schema of inputs inferred from the function signature.

When stored in repositories, these are separated into <path>.ts and <path>.script.yaml files.

Creating a script

From the Home page, click +Script to begin. This opens the metadata configuration step.

Settings & metadata

Key metadata fields include:

• Summary: Short, human-readable title (optional; defaults to path)
• Path: Unique identifier combining owner and script name
• Description: Instructions supporting markdown
• Language: Script language selection
• Script kind: Action (default), Trigger, Approval, Error handler, or Preprocessor

Additional settings cover Runtime, Generated UI, and Triggers configuration.

Code editor

The left side contains the editor; the right side previews the auto-generated UI based on the function signature. You can test scripts directly within the editor.

The boilerplate provides:

export async function main(
  a: number,
  b: "my" | "enum",
  e = "inferred type string from default arg",
  f = { nested: "object" },
  g: {
    label: "Variant 1",
    foo: string
  } | {
    label: "Variant 2",
    bar: number
  }) {
  return { foo: a };
}

Key points about main:

• Arguments generate input specifications and frontend forms.
• Type annotations create UI forms and pre-validate inputs.
• Annotations are recommended but not mandatory.

A simple example:

export async function main(name: string) {
  console.log("Hello world! Oh, it's you %s? Greetings!", name);
  return { name };
}

Runtime modes

Pre-bundling and nobundling

Orvanta pre-bundles scripts at deployment using the Bun bundler for improved memory usage and speed. Disable with:

//nobundling

Native

A lightweight runtime with limited features using direct v8 bindings:

//native

Node.js

True Node.js compatibility mode available on Cloud plans and Self-Hosted Enterprise:

//nodejs

npm

Use npm instead of bun for package installation (exclusive to Cloud and Enterprise):

//npm

Deno

Deno uses the npm: prefix for npm imports:

import * as orvanta from "npm:[email protected]"

Deno handles dependency resolution independently.

Testing and preview

The UI preview updates automatically when you modify the function signature. Test scripts using Ctrl+Enter. Adding defaults to arguments makes fields optional in the UI:

main(name: string = "you")

Generated UI customization

The Generated UI settings tab allows customizing arguments beyond the function signature. You can add constraints like regex patterns. For example, restrict input to alphanumeric: ^[A-Za-z0-9]+$.

Workflows as code

For distributed programs with distinct jobs, use “workflows as code” by wrapping orchestration with workflow() and annotating tasks with task(). Each task executes as a separate job with individual logs and timeline entries, while the workflow pauses between tasks.

Deployment and execution

Click Deploy to finalize the script. Scripts are versioned in Orvanta with unique hash identifiers per version. Fill input fields and click Run to execute. All runs appear in the Runs menu on the left sidebar.

Scripts can also be executed via CLI with pre-generated commands.

Caching

All Bun bundles cache on disk by default. Distributed cache storage makes bundles available across workers, enabling fast startup times.

Next steps

• Pass variables and secrets to scripts
• Connect to resources
• Trigger scripts through various methods
• Compose scripts into Flows or Apps
• Share scripts on the Orvanta Hub for community use

Scripts are immutable; each deployment receives a unique hash. Referencing a script by path accesses the latest deployed hash.