Command Line Interface

macroforge v0.1.77

This binary provides command-line utilities for working with Macroforge TypeScript macros. It is designed for development workflows, enabling macro expansion and type checking without requiring Node.js integration.

Installation

The CLI is a Rust binary. You can install it using Cargo:

cargo install macroforge_ts

Or build from source:

git clone https://github.com/macroforge-ts/zed-extensions.git
cd macroforge-ts/crates
cargo build --release --bin macroforge

# The binary is at target/release/macroforge

Commands

macroforge expand

Expands macros in a TypeScript file and outputs the transformed code.

macroforge expand <input> [options]

Arguments

Options

Examples

Expand a file and print to stdout:

macroforge expand src/user.ts

Expand and write to a file:

macroforge expand src/user.ts --out dist/user.js

Expand with both runtime output and type declarations:

macroforge expand src/user.ts --out dist/user.js --types-out dist/user.d.ts

Use fast built-in macros only (no external macro support):

macroforge expand src/user.ts --builtin-only

macroforge tsc

Runs TypeScript type checking with macro expansion. This wraps tsc --noEmit and expands macros before type checking, so your generated methods are properly type-checked.

macroforge tsc [options]

Options

Examples

Type check with default tsconfig.json:

macroforge tsc

Type check with a specific config:

macroforge tsc -p tsconfig.build.json

macroforge svelte-check

Runs svelte-check with macro expansion, so Svelte components using macros are properly type-checked.

macroforge svelte-check [options]

Options

macroforge watch

Watches source files and maintains the macro expansion cache, keeping it up to date as files change.

macroforge watch [root] [options]

Options

macroforge cache

Builds the .macroforge/cache directory once for all source files. Useful for CI or pre-build steps.

macroforge cache [root] [options]

Options

macroforge refresh

Deletes and rebuilds the macro cache from scratch.

macroforge refresh [root] [options]

Options

Output Format

Expanded Code

When expanding a file like this:

/** @derive(Debug) */
class User {
  name: string;
  age: number;

  constructor(name: string, age: number) {
    this.name = name;
    this.age = age;
  }
}

The CLI outputs the expanded code with the generated methods:

class User {
  name: string;
  age: number;

  constructor(name: string, age: number) {
    this.name = name;
    this.age = age;
  }

  [Symbol.for("nodejs.util.inspect.custom")](): string {
    return `User { name: ${this.name}, age: ${this.age} }`;
  }
}

Diagnostics

Errors and warnings are printed to stderr in a readable format:

[macroforge] error at src/user.ts:5:1: Unknown derive macro: InvalidMacro
[macroforge] warning at src/user.ts:10:3: Field 'unused' is never used

Use Cases

CI/CD Type Checking

Use macroforge tsc in your CI pipeline to type-check with macro expansion:

# package.json
{
  "scripts": {
    "typecheck": "macroforge tsc"
  }
}

Debugging Macro Output

Use macroforge expand to inspect what code your macros generate:

macroforge expand src/models/user.ts | less

Build Pipeline

Generate expanded files as part of a custom build:

#!/bin/bash
for file in src/**/*.ts; do
  outfile="dist/$(basename "$file" .ts).js"
  macroforge expand "$file" --out "$outfile"
done

Built-in vs Full Mode

By default, the CLI uses Node.js for full macro support including external macros. Use --builtin-only for faster expansion when you only need built-in macros: