{"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,"search_vec":"'activ':7 'api':59 'async':46 'babel':34 'call':19 'code':28 'compil':14,26,73 'compile-tim':25,72 'complex':50 'comput':22 'date':55 'declar':67 'develop':8 'differenti':32 'enabl':24 'esbuild':4,39,71 'esbuild-n':38 'esm':43 'esm-on':42 'execut':10 'function':12 'generat':29 'includ':68 'javascript':69 'like':52 'macro':3,35,47,70 'map':53 'nativ':40 'npm':63 'object':60 'optim':31 'plugin':5,75 'regexp':56 'releas':61 'replac':17 'result':23 'serial':49 'set':54 'support':45 'time':15,27,74 'type':51,66 'typescript':65,76 'typescript/javascript':11 'use':2 'use-macro':1 'v1.1.0':6 'web':58","created_at":"2026-05-01T13:50:41.607582+00:00","updated_at":"2026-05-01T13:50:41.607582+00:00","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,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/twlite/use-macro","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/use-macro","openapi_spec":null,"status_page":null,"smithery":null,"categories":["devops","web-framework"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-05-01","next_check":"2026-07-30","install_tag":null}}