Amaro TypeScript Wrapper

raw JSON →
1.1.8 verified Sun Apr 19 auth: no javascript

Amaro is a low-level Node.js wrapper around `@swc/wasm-typescript`, a WebAssembly port of the SWC TypeScript parser. It primarily performs type stripping, which is utilized internally by Node.js for its native TypeScript support. As of its latest stable release, version 1.1.8, Amaro offers a stable API that allows developers to use a specific TypeScript transpiler version independently of the one embedded in Node.js. The package sees frequent updates, often aligning with new SWC versions. Its key differentiators include synchronous type stripping (`transformSync`), flexible loader mechanisms (`amaro/strip`, `amaro/transform`) for direct execution of TypeScript files, and enhanced monorepo development workflows via conditional exports, abstracting away build steps. It currently supports TypeScript version 5.8.

error 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);
error 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 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.
error 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.
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`.
npm install amaro
yarn add amaro
pnpm add amaro

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
*/