Amaro TypeScript Wrapper

Common errors

• TypeError: amaro.register is not a function

  cause Attempting to use the `amaro.register` API which was removed in `v1.0.0`.
  fix For direct CLI usage, switch to `node --import="amaro/strip"`. For programmatic registration, use `import { register } from "node:module"; register("amaro/strip", import.meta.url);`

• SyntaxError: Cannot use import statement outside a module

  cause Attempting to `import` an ESM-only loader (like `amaro/strip`) in a CommonJS context without proper configuration, or when Node.js cannot resolve the module as ESM.
  fix Ensure your project is configured as an ESM module (`"type": "module"` in `package.json`) or that the file using `import` has an `.mjs` extension. If activating the loader via CLI, use the recommended `node --import="amaro/strip"` syntax.

• Error: Missing "typescript" condition for "."

  cause You are using `exports` in `package.json` with a `"typescript"` condition but have not told Node.js to enable this condition.
  fix Run Node.js with the `--conditions=typescript` flag: `node --conditions=typescript --import="amaro/strip" your-app.ts`.

• ReferenceError: require is not defined

  cause Attempting to use `require()` in an ES Module context (`.mjs` file or `"type": "module"` project).
  fix Migrate your code to use `import` statements or ensure your files are treated as CommonJS modules by using `.cjs` extensions or omitting `"type": "module"` in `package.json`.

Warnings

• breaking The `amaro/register` loader, available in versions prior to `v1.0.0`, has been removed.
  Fix: Migrate to using Node.js's native `--import` flag with `amaro/strip` or `amaro/transform`, or use the `node:module` `register()` API for programmatic loader registration.
• gotcha When using the `amaro/transform` loader for TypeScript feature transformation, `--enable-source-maps` is crucial for accurate stack traces.
  Fix: Always include the `--enable-source-maps` flag when running Node.js with `amaro/transform`: `node --enable-source-maps --import="amaro/transform" file.ts`.
• gotcha Amaro requires Node.js version 22 or higher to function correctly.
  Fix: Upgrade your Node.js runtime to version 22 or newer to meet the `engines` requirement specified in `package.json`.
• gotcha When using Amaro in monorepos with `exports` conditions that include `"typescript": "./src/index.ts"`, you must specify `--conditions=typescript`.
  Fix: Ensure the `--conditions=typescript` flag is passed to Node.js when leveraging TypeScript conditional exports: `node --import="amaro/strip" --conditions=typescript ./src/index.ts`.

Install

• npm install amaro npm
• yarn add amaro yarn
• pnpm add amaro pnpm

Imports

• transformSync
  wrong:

  const amaro = require('amaro');
  const { transformSync } = amaro;

  correct:

  import amaro from 'amaro';
  const { transformSync } = amaro;

  While `require` works, `import` is preferred in modern Node.js ESM projects. `transformSync` is a named export from the default import object.
• amaro/strip loader
  wrong:

  import 'amaro/strip';

  correct:

  node --import="amaro/strip" file.ts

  The loader is typically activated via Node.js CLI flags, not through direct `import` statements in application code, unless part of a `module.register` bootstrap.
• amaro/transform loader

  node --enable-source-maps --import="amaro/transform" file.ts

  Always use `--enable-source-maps` with `amaro/transform` for accurate stack traces.
• register (for programmatic loaders)
  wrong:

  import { register } from 'amaro';

  correct:

  import { register } from "node:module";
  register("amaro/strip", import.meta.url);

  The `register` function is part of Node.js's built-in `node:module` and is used to register Amaro's loaders programmatically.

Quickstart

This quickstart demonstrates synchronous type stripping using `amaro.transformSync` and provides examples of how to activate Amaro as a Node.js loader for direct TypeScript execution.

import amaro from 'amaro';

const tsCode = `
  interface User {
    id: number;
    name: string;
  }

  function greet(user: User): string {
    return \`Hello, \${user.name}!\`;
  }

  const myUser: User = { id: 1, name: 'Alice' };
  console.log(greet(myUser));
`;

console.log("Original TypeScript Code:");
console.log(tsCode);

// Use transformSync to strip types. 
// The 'strip-only' mode replaces type annotations with whitespace 
// to preserve original line numbers for stack traces.
const { code: strippedCode } = amaro.transformSync(tsCode, { mode: "strip-only" });

console.log("\nTransformed JavaScript Code (types stripped):\n---\n");
console.log(strippedCode);
console.log("\n---\n");

/*
// To use Amaro as a Node.js loader to execute TypeScript files directly:

// 1. Create a file named 'my-app.ts':
//    const message: string = "Hello from Amaro loader!";
//    console.log(message);

// 2. Run with Node.js using the --import flag (for type stripping):
//    node --import="amaro/strip" my-app.ts

// 3. For more advanced features (like decorators, class fields) and source maps:
//    node --enable-source-maps --import="amaro/transform" my-app.ts

// 4. For programmatic loader registration (e.g., in a bootstrap file):
//    // bootstrap.mjs
//    import { register } from "node:module";
//    register("amaro/strip", import.meta.url);
//    await import("./my-app.ts");
//    // Then run: node --watch ./bootstrap.mjs
*/