Amaro TypeScript Wrapper
raw JSON →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.
Common errors
error TypeError: amaro.register is not a function ↓
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 ↓
"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 "." ↓
--conditions=typescript flag: node --conditions=typescript --import="amaro/strip" your-app.ts. error ReferenceError: require is not defined ↓
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. ↓
gotcha When using the `amaro/transform` loader for TypeScript feature transformation, `--enable-source-maps` is crucial for accurate stack traces. ↓
gotcha Amaro requires Node.js version 22 or higher to function correctly. ↓
gotcha When using Amaro in monorepos with `exports` conditions that include `"typescript": "./src/index.ts"`, you must specify `--conditions=typescript`. ↓
Install
npm install amaro yarn add amaro pnpm add amaro Imports
- transformSync wrong
const amaro = require('amaro'); const { transformSync } = amaro;correctimport amaro from 'amaro'; const { transformSync } = amaro; - amaro/strip loader wrong
import 'amaro/strip';correctnode --import="amaro/strip" file.ts - amaro/transform loader
node --enable-source-maps --import="amaro/transform" file.ts - register (for programmatic loaders) wrong
import { register } from 'amaro';correctimport { register } from "node:module"; register("amaro/strip", import.meta.url);
Quickstart
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
*/