use-macro

library1.1.0jsnpmunverified

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.

devops web-framework

npm install use-macro

github ↗package ↗

INSTALL

IMPORT

SIG · USE-MACRO

use-macro

devopsjavascriptv1.1.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

esbuildPluginUseMacro

✓ import { esbuildPluginUseMacro } from 'use-macro'

✗ import useMacro from 'use-macro'

Default export not available; must use named import. ESM only, no CommonJS support.

MacroTransformer

✓ import { MacroTransformer } from 'use-macro'

✗ const { MacroTransformer } = require('use-macro')

Package is ESM-only; require() will throw an error. MacroTransformer is a class for standalone transform usage.

plugin (default)

✓ import { esbuildPluginUseMacro } from 'use-macro'; const plugin = esbuildPluginUseMacro(options)

✗ import useMacro from 'use-macro'; const plugin = useMacro(options)

No default export; the correct way is to use the named export and call it as a function.

Basic esbuild integration: registers the plugin and uses a macro to inline a compile-time Date.

import { build } from 'esbuild'; import { esbuildPluginUseMacro } from 'use-macro'; build({ entryPoints: ['src/index.ts'], bundle: true, outfile: 'dist/index.js', plugins: [esbuildPluginUseMacro()], }).catch(() => process.exit(1)); // In src/index.ts: function $compiledAt(): Date { 'use macro'; return new Date(); } export const compiledAt = $compiledAt();

Debug

Known issues

breakingThe package is ESM-only and does not support CommonJS require() or Node's --experimental-require-module.

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).

affects: >=1.0.0

gotchaMacro functions must include 'use macro' directive; otherwise they execute at runtime and import/require inside them may fail at build time.

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.

affects: >=1.0.0

gotchaMacro functions are isolated and cannot access outer scope variables; any dependency must be imported or required inside the macro body.

fix

Move all required imports inside the macro function. The macro cannot reference variables from the enclosing module scope.

affects: >=1.0.0

deprecatedVersion 1.0.0 had a bug where async macros were not correctly awaited in some edge cases; fixed in 1.1.0.

fix

Update to version 1.1.0 or later.

affects: 1.0.0

Errors

Common errors & fixes

Error [ERR_REQUIRE_ESM]: require() of ES Module not supported.

Using require() to import 'use-macro', which is ESM-only.

fix

Use import statement instead: import { esbuildPluginUseMacro } from 'use-macro'

TypeError: esbuildPluginUseMacro is not a function

Attempting to use an incorrectly imported value, possibly the default export which does not exist.

fix

Use named import: import { esbuildPluginUseMacro } from 'use-macro' and then call it: esbuildPluginUseMacro(options)

ReferenceError: require is not defined (or module is not defined) inside macro function

Using require in a JavaScript/ESM environment without bundling; but for macros, require is allowed if the bundler (esbuild) provides it.

fix

Ensure esbuild is set to bundle the code. If using tsup, enable esbuild bundling. For standalone transformer, provide a custom module resolution.

Upgrade

Version history

1.1.0latest on npm

Audit

Dependencies

esbuildrequiredRuntime peer dependency; the plugin integrates into esbuild's build pipeline.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/twlite/use-macro ↗

packagehttps://www.npmjs.com/package/use-macro ↗