{"id":26574,"library":"use-macro","title":"use-macro","description":"ESBuild plugin (v1.1.0, active development) that executes TypeScript/JavaScript functions at compile time and replaces their calls with the computed result, enabling compile-time code generation and optimization. Differentiates from Babel macros by being esbuild-native and ESM-only, supporting async macros, and serializing complex types like Map, Set, Date, RegExp, and web API objects. Released on npm, with TypeScript type declarations included.","status":"active","version":"1.1.0","language":"javascript","source_language":"en","source_url":"https://github.com/twlite/use-macro","tags":["javascript","macro","esbuild","compile-time","plugin","typescript"],"install":[{"cmd":"npm install use-macro","lang":"bash","label":"npm"},{"cmd":"yarn add use-macro","lang":"bash","label":"yarn"},{"cmd":"pnpm add use-macro","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Runtime peer dependency; the plugin integrates into esbuild's build pipeline.","package":"esbuild","optional":false}],"imports":[{"note":"Default export not available; must use named import. ESM only, no CommonJS support.","wrong":"import useMacro from 'use-macro'","symbol":"esbuildPluginUseMacro","correct":"import { esbuildPluginUseMacro } from 'use-macro'"},{"note":"Package is ESM-only; require() will throw an error. MacroTransformer is a class for standalone transform usage.","wrong":"const { MacroTransformer } = require('use-macro')","symbol":"MacroTransformer","correct":"import { MacroTransformer } from 'use-macro'"},{"note":"No default export; the correct way is to use the named export and call it as a function.","wrong":"import useMacro from 'use-macro'; const plugin = useMacro(options)","symbol":"plugin (default)","correct":"import { esbuildPluginUseMacro } from 'use-macro'; const plugin = esbuildPluginUseMacro(options)"}],"quickstart":{"code":"import { build } from 'esbuild';\nimport { esbuildPluginUseMacro } from 'use-macro';\n\nbuild({\n  entryPoints: ['src/index.ts'],\n  bundle: true,\n  outfile: 'dist/index.js',\n  plugins: [esbuildPluginUseMacro()],\n}).catch(() => process.exit(1));\n\n// In src/index.ts:\nfunction $compiledAt(): Date {\n  'use macro';\n  return new Date();\n}\nexport const compiledAt = $compiledAt();","lang":"typescript","description":"Basic esbuild integration: registers the plugin and uses a macro to inline a compile-time Date."},"warnings":[{"fix":"Use ESM imports ('import' instead of 'require') and ensure project is configured for ESM (e.g., type: 'module' in package.json or .mjs extension).","message":"The package is ESM-only and does not support CommonJS require() or Node's --experimental-require-module.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Add 'use macro'; as the first statement in any function intended as a macro. The directive is a string literal, not a pragma comment.","message":"Macro functions must include 'use macro' directive; otherwise they execute at runtime and import/require inside them may fail at build time.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Move all required imports inside the macro function. The macro cannot reference variables from the enclosing module scope.","message":"Macro functions are isolated and cannot access outer scope variables; any dependency must be imported or required inside the macro body.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Update to version 1.1.0 or later.","message":"Version 1.0.0 had a bug where async macros were not correctly awaited in some edge cases; fixed in 1.1.0.","severity":"deprecated","affected_versions":"1.0.0"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Use import statement instead: import { esbuildPluginUseMacro } from 'use-macro'","cause":"Using require() to import 'use-macro', which is ESM-only.","error":"Error [ERR_REQUIRE_ESM]: require() of ES Module not supported."},{"fix":"Use named import: import { esbuildPluginUseMacro } from 'use-macro' and then call it: esbuildPluginUseMacro(options)","cause":"Attempting to use an incorrectly imported value, possibly the default export which does not exist.","error":"TypeError: esbuildPluginUseMacro is not a function"},{"fix":"Ensure esbuild is set to bundle the code. If using tsup, enable esbuild bundling. For standalone transformer, provide a custom module resolution.","cause":"Using require in a JavaScript/ESM environment without bundling; but for macros, require is allowed if the bundler (esbuild) provides it.","error":"ReferenceError: require is not defined (or module is not defined) inside macro function"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}