{"id":28412900,"url":"https://github.com/neplextech/use-macro","last_synced_at":"2025-06-24T18:31:38.282Z","repository":{"id":269644659,"uuid":"908101403","full_name":"neplextech/use-macro","owner":"neplextech","description":"use-macro allows you to execute functions at compile time and inline the output","archived":false,"fork":false,"pushed_at":"2025-01-14T07:29:05.000Z","size":46,"stargazers_count":6,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-11T10:09:56.168Z","etag":null,"topics":["compile-time","esbuild","esbuild-plugin","inline","javascript","macro","typescript"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/use-macro","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/neplextech.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-12-25T06:14:09.000Z","updated_at":"2025-04-13T21:02:11.000Z","dependencies_parsed_at":null,"dependency_job_id":"82dbc8b8-ac68-4ca5-a0b1-0e8ed19d8f85","html_url":"https://github.com/neplextech/use-macro","commit_stats":null,"previous_names":["twlite/use-macro","neplextech/use-macro"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/neplextech/use-macro","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/neplextech%2Fuse-macro","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/neplextech%2Fuse-macro/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/neplextech%2Fuse-macro/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/neplextech%2Fuse-macro/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/neplextech","download_url":"https://codeload.github.com/neplextech/use-macro/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/neplextech%2Fuse-macro/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260359352,"owners_count":22997265,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["compile-time","esbuild","esbuild-plugin","inline","javascript","macro","typescript"],"created_at":"2025-06-03T02:13:22.832Z","updated_at":"2025-06-24T18:31:38.266Z","avatar_url":"https://github.com/neplextech.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ESBuild Plugin Use Macro\n\nThis is a plugin for [esbuild](https://esbuild.github.io/) that allows you to use macros in your code. Macros are a way to define a function that will be executed at compile time, and will replace the macro call with the result of the function.\n\n\u003e Note: This package is esm only.\n\n## Features\n\n- [x] Macros are defined as regular functions that are marked with the `use macro` directive.\n- [x] Macro functions can be async.\n- [x] Macro functions are automatically awaited.\n- [x] Supports serialization of various types like primitive types, Map, Set, Date, RegExp, and Request, Response, FormData, URL, URLSearchParams, and more.\n- [x] Macro functions are self contained, they cannot access the scope of the calling code.\n\n## Installation\n\n```bash\nnpm install use-macro\n```\n\n## Usage\n\n### Lets create a simple macro that will extract the version from the package.json file\n\n\u003c!-- prettier-ignore --\u003e\n```typescript\nfunction $version(): string {\n  'use macro';\n  const { version } = require('../package.json');\n  console.log(`Version: ${version}`);\n\n  return version;\n}\n\nfunction $compiledAt(): Date {\n  'use macro';\n  return new Date();\n}\n\nasync function $message(): Promise\u003cstring\u003e {\n  'use macro';\n\n  const fs = require('fs').promises;\n  const path = require('path');\n  const messageText = path.resolve(__dirname, 'message.txt');\n  const res = await fs.readFile(messageText, 'utf8');\n\n  return res;\n}\n\nconst $url = () =\u003e {\n  'use macro';\n  const url = new URL('https://example.com?foo=bar\u0026baz=qux');\n\n  return [url, url.searchParams];\n};\n\nconst $formData = function () {\n  'use macro';\n  const formData = new FormData();\n  formData.append('foo', 'bar');\n  formData.append('baz', 'qux');\n\n  return formData;\n};\n\nexport const version = $version();\nexport const compiledAt = $compiledAt();\nexport const message = $message() as unknown as Awaited\u003cReturnType\u003ctypeof $message\u003e\u003e;\nexport const url = $url();\nexport const formData = $formData();\n```\n\n### Now lets register the macro in the esbuild plugin\n\n```typescript\nimport { 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(() =\u003e process.exit(1));\n```\n\n\u003e Note: You can also use this plugin with [tsup](https://tsup.egoist.sh/) by passing the `esbuildOptions` object to the `tsup` function.\n\n### Now lets run the build. The output will be:\n\n\u003c!-- prettier-ignore --\u003e\n```javascript\n// src/index.ts\nvar version = (\n  /* @__MACRO__ $version */\n  \"1.0.0\"\n);\nvar compiledAt = (\n  /* @__MACRO__ $compiledAt */\n  /* @__PURE__ */ new Date(1736839318808)\n);\nvar message = (\n  /* @__MACRO__ $message */\n  \"Hello World!\"\n);\nvar url = (\n  /* @__MACRO__ $url */\n  [new URL(\"https://example.com/?foo=bar\u0026baz=qux\"), new URLSearchParams([[\"foo\", \"bar\"], [\"baz\", \"qux\"]])]\n);\nvar formData = (\n  /* @__MACRO__ $formData */\n  new FormData([[\"foo\", \"bar\"], [\"baz\", \"qux\"]])\n);\nexport {\n  compiledAt,\n  formData,\n  message,\n  url,\n  version\n};\n```\n\nNotice how entire function was removed and the function call was replaced with the result of the function.\n\n## Transformer API (Usage without esbuild)\n\n`use-macro` can be used without esbuild as a standalone transformer. This can be useful if you want to use macros in other tools programmatically.\n\n```typescript\nimport { MacroTransformer } from 'use-macro';\n\nconst transformer = new MacroTransformer();\n\nconst code = `\nfunction $random(): number {\n  'use macro';\n  return Math.random();\n}\n`;\n\n/**\n * The first argument is the code to transform.\n * The second argument is the file name, this is used to resolve relative imports.\n */\nconst result = transformer.transform(code, 'file.ts');\n\n/*\n{\n  content: '...',\n  loader: 'ts'\n}\n*/\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fneplextech%2Fuse-macro","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fneplextech%2Fuse-macro","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fneplextech%2Fuse-macro/lists"}