{"id":10493,"library":"amaro","title":"Amaro TypeScript Wrapper","description":"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.","status":"active","version":"1.1.8","language":"javascript","source_language":"en","source_url":"https://github.com/nodejs/amaro","tags":["javascript","typescript","nodejs","type stripping","strip-types"],"install":[{"cmd":"npm install amaro","lang":"bash","label":"npm"},{"cmd":"yarn add amaro","lang":"bash","label":"yarn"},{"cmd":"pnpm add amaro","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"While `require` works, `import` is preferred in modern Node.js ESM projects. `transformSync` is a named export from the default import object.","wrong":"const amaro = require('amaro');\nconst { transformSync } = amaro;","symbol":"transformSync","correct":"import amaro from 'amaro';\nconst { transformSync } = amaro;"},{"note":"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.","wrong":"import 'amaro/strip';","symbol":"amaro/strip loader","correct":"node --import=\"amaro/strip\" file.ts"},{"note":"Always use `--enable-source-maps` with `amaro/transform` for accurate stack traces.","symbol":"amaro/transform loader","correct":"node --enable-source-maps --import=\"amaro/transform\" file.ts"},{"note":"The `register` function is part of Node.js's built-in `node:module` and is used to register Amaro's loaders programmatically.","wrong":"import { register } from 'amaro';","symbol":"register (for programmatic loaders)","correct":"import { register } from \"node:module\";\nregister(\"amaro/strip\", import.meta.url);"}],"quickstart":{"code":"import amaro from 'amaro';\n\nconst tsCode = `\n  interface User {\n    id: number;\n    name: string;\n  }\n\n  function greet(user: User): string {\n    return \\`Hello, \\${user.name}!\\`;\n  }\n\n  const myUser: User = { id: 1, name: 'Alice' };\n  console.log(greet(myUser));\n`;\n\nconsole.log(\"Original TypeScript Code:\");\nconsole.log(tsCode);\n\n// Use transformSync to strip types. \n// The 'strip-only' mode replaces type annotations with whitespace \n// to preserve original line numbers for stack traces.\nconst { code: strippedCode } = amaro.transformSync(tsCode, { mode: \"strip-only\" });\n\nconsole.log(\"\\nTransformed JavaScript Code (types stripped):\\n---\\n\");\nconsole.log(strippedCode);\nconsole.log(\"\\n---\\n\");\n\n/*\n// To use Amaro as a Node.js loader to execute TypeScript files directly:\n\n// 1. Create a file named 'my-app.ts':\n//    const message: string = \"Hello from Amaro loader!\";\n//    console.log(message);\n\n// 2. Run with Node.js using the --import flag (for type stripping):\n//    node --import=\"amaro/strip\" my-app.ts\n\n// 3. For more advanced features (like decorators, class fields) and source maps:\n//    node --enable-source-maps --import=\"amaro/transform\" my-app.ts\n\n// 4. For programmatic loader registration (e.g., in a bootstrap file):\n//    // bootstrap.mjs\n//    import { register } from \"node:module\";\n//    register(\"amaro/strip\", import.meta.url);\n//    await import(\"./my-app.ts\");\n//    // Then run: node --watch ./bootstrap.mjs\n*/","lang":"typescript","description":"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."},"warnings":[{"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.","message":"The `amaro/register` loader, available in versions prior to `v1.0.0`, has been removed.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Always include the `--enable-source-maps` flag when running Node.js with `amaro/transform`: `node --enable-source-maps --import=\"amaro/transform\" file.ts`.","message":"When using the `amaro/transform` loader for TypeScript feature transformation, `--enable-source-maps` is crucial for accurate stack traces.","severity":"gotcha","affected_versions":"*"},{"fix":"Upgrade your Node.js runtime to version 22 or newer to meet the `engines` requirement specified in `package.json`.","message":"Amaro requires Node.js version 22 or higher to function correctly.","severity":"gotcha","affected_versions":"<22"},{"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`.","message":"When using Amaro in monorepos with `exports` conditions that include `\"typescript\": \"./src/index.ts\"`, you must specify `--conditions=typescript`.","severity":"gotcha","affected_versions":"*"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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);`","cause":"Attempting to use the `amaro.register` API which was removed in `v1.0.0`.","error":"TypeError: amaro.register is not a function"},{"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.","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.","error":"SyntaxError: Cannot use import statement outside a module"},{"fix":"Run Node.js with the `--conditions=typescript` flag: `node --conditions=typescript --import=\"amaro/strip\" your-app.ts`.","cause":"You are using `exports` in `package.json` with a `\"typescript\"` condition but have not told Node.js to enable this condition.","error":"Error: Missing \"typescript\" condition for \".\""},{"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`.","cause":"Attempting to use `require()` in an ES Module context (`.mjs` file or `\"type\": \"module\"` project).","error":"ReferenceError: require is not defined"}],"ecosystem":"npm"}