@launchfile/sdk

TypeScript SDK for parsing, validating, and serializing Launchfiles.

Install

bun add launchfile
# or
npm install launchfile

CLI

The SDK includes a launchfile CLI for validating and inspecting Launchfiles.

# Validate a Launchfile (defaults to ./Launchfile)
launchfile validate
launchfile validate path/to/Launchfile

# Structured JSON output for CI pipelines
launchfile validate --json

# Silent mode — just the exit code
launchfile validate --quiet

# Print the normalized form (after shorthand expansion) as JSON
launchfile inspect path/to/Launchfile

# Dump the JSON Schema to stdout
launchfile schema

Global flags

--no-color — Disable colored output (also respects NO_COLOR env var)
--version — Print version
--help — Show usage

Validate in CI

# GitHub Actions
- run: npx launchfile validate --quiet

Editor Integration

Add JSON Schema support for autocompletion and validation in your editor:

# yaml-language-server: $schema=https://launchfile.dev/schema/v1
version: launch/v1
name: my-app

Usage

Parse a Launchfile

import { readLaunch } from "launchfile";

const app = readLaunch(`
  name: my-app
  runtime: node
  requires: [postgres]
  commands:
    start: "node server.js"
  health: /health
`);

// app.components.default.requires → [{ type: "postgres" }]
// app.components.default.health → { path: "/health" }

Validate pre-parsed data

import { validateLaunch } from "launchfile";

const app = validateLaunch({
  name: "my-app",
  runtime: "node",
  requires: ["postgres"],
});

Write back to YAML

import { writeLaunch } from "launchfile";

const yaml = writeLaunch(app);
// Collapses shorthands: { type: "postgres" } → "postgres"

Resolve expressions

import { resolveExpression } from "launchfile";

const url = resolveExpression("postgresql://${host}:${port}/${name}", {
  resource: { host: "localhost", port: 5432, name: "mydb" },
});
// → "postgresql://localhost:5432/mydb"

Check for expressions

import { isExpression } from "launchfile";

isExpression("$url");           // true
isExpression("hello");          // false
isExpression("$$escaped");      // false (literal $)

API

Function	Description
`readLaunch(yaml)`	Parse YAML string → validated, normalized `NormalizedLaunch`
`validateLaunch(data)`	Validate a parsed object → `NormalizedLaunch`
`writeLaunch(launch)`	Serialize `NormalizedLaunch` → compact YAML string
`parseExpression(value)`	Parse a `$`-expression into an AST
`resolveExpression(value, context)`	Resolve expression against a context → string
`isExpression(value)`	Check if a string contains `$` references
`parseDotPath(path)`	Parse `"a.b.c"` → `["a", "b", "c"]`
`LaunchSchema`	Zod schema for direct validation

Types

All types are exported:

import type {
  Launch,
  NormalizedLaunch,
  Component,
  NormalizedComponent,
  Requirement,
  Provides,
  EnvVar,
  // ... see types.ts for full list
} from "launchfile";

License

MIT