Installation

Get started with Macroforge in just a few minutes. Install the package and configure your project to start using TypeScript macros.

Requirements

Node.js 24.0 or later (for native bindings)
A WebAssembly-compatible environment (for WASM version)
TypeScript 5.9 or later

Install the Package

Install Macroforge using your preferred package manager:

npm

npm install macroforge

bun

bun add macroforge

pnpm

pnpm add macroforge

Info

Macroforge provides two distribution options:

Native Bindings: Pre-built binaries for macOS, Linux, and Windows. Used by default in Node.js.
WebAssembly: A universal @macroforge/wasm package for browser, edge, and other environments.

Basic Usage

The simplest way to use Macroforge is with the built-in derive macros. Add a @derive comment decorator to your class:

user.ts

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

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

// After macro expansion, User has:
// - static toString(value: User): string          (from Debug)
// - static clone(value: User): User               (from Clone)
// - static equals(a: User, b: User): boolean      (from PartialEq)

IDE Integration

For the best development experience, add the TypeScript plugin to your tsconfig.json:

tsconfig.json

{
  "compilerOptions": {
    "plugins": [
      {
        "name": "@macroforge/typescript-plugin"
      }
    ]
  }
}

This enables features like:

Accurate error positions in your source code
Autocompletion for generated methods
Type checking for expanded code

Build Integration (Vite)

If you're using Vite, add the plugin to your config for automatic macro expansion during build:

vite.config.ts

import { macroforge } from "@macroforge/vite-plugin";
import { defineConfig } from "vite";

export default defineConfig({
  plugins: [
    macroforge()
  ]
});

Next Steps

Now that you have Macroforge installed, learn how to use it: