{"id":31577460,"url":"https://github.com/sushichan044/unplugin-transform-import-meta","last_synced_at":"2026-01-20T17:35:10.885Z","repository":{"id":313493485,"uuid":"1044960677","full_name":"sushichan044/unplugin-transform-import-meta","owner":"sushichan044","description":"Transform ImportMeta properties and methods at build-time.","archived":false,"fork":false,"pushed_at":"2025-09-12T14:24:13.000Z","size":386,"stargazers_count":0,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-03T20:45:43.927Z","etag":null,"topics":["ecmascript","import-meta","unplugin"],"latest_commit_sha":null,"homepage":"","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/sushichan044.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-08-26T13:02:59.000Z","updated_at":"2025-09-10T15:53:06.000Z","dependencies_parsed_at":"2025-09-06T13:19:07.340Z","dependency_job_id":"1f2f2773-31fe-4629-b207-e416b7d0e400","html_url":"https://github.com/sushichan044/unplugin-transform-import-meta","commit_stats":null,"previous_names":["sushichan044/unplugin-transform-import-meta"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/sushichan044/unplugin-transform-import-meta","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sushichan044%2Funplugin-transform-import-meta","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sushichan044%2Funplugin-transform-import-meta/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sushichan044%2Funplugin-transform-import-meta/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sushichan044%2Funplugin-transform-import-meta/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sushichan044","download_url":"https://codeload.github.com/sushichan044/unplugin-transform-import-meta/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sushichan044%2Funplugin-transform-import-meta/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278496349,"owners_count":25996793,"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","status":"online","status_checked_at":"2025-10-05T02:00:06.059Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["ecmascript","import-meta","unplugin"],"created_at":"2025-10-05T18:24:35.567Z","updated_at":"2025-10-05T18:24:37.084Z","avatar_url":"https://github.com/sushichan044.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# unplugin-transform-import-meta\n\n[![npm version][npm-version-src]][npm-version-href]\n[![npm downloads][npm-downloads-src]][npm-downloads-href]\n\n\u003e [!WARNING]\n\u003e\n\u003e Extending `import.meta` is not something to do lightly.\n\u003e\n\u003e Please read the guidance and reserved key registry in WinterTC's import-meta-registry before using this plugin: \u003chttps://github.com/WinterTC55/import-meta-registry\u003e.\n\u003e\n\u003e This plugin targets library/framework authors who have a strong, well‑justified need for build‑time only metadata. In most application-level cases you should not need this plugin.\n\u003e\n\u003e Prefer official mechanisms from your bundler/platform (e.g. environment variables, define/replace features, virtual modules, configuration files) before introducing custom `import.meta.*` keys.\n\nTransform `import.meta.*` properties and methods at build-time across Vite, Rollup, Webpack, Rspack, esbuild, Rolldown, and Farm.\n\n- Replace `import.meta.SOME_PROP` with literals (string/number/boolean/bigint/RegExp/null)\n- Evaluate `import.meta.someMethod(...)` with your function and inline the literal result\n- Guard against reserved `import.meta` keys for each bundler and common registries\n\nESM-only. Requires Node.js \u003e= 20.19.0.\n\n## Install\n\n```bash\nnpm i -D unplugin-transform-import-meta\n# pnpm add -D unplugin-transform-import-meta\n# yarn add -D unplugin-transform-import-meta\n# bun add -d unplugin-transform-import-meta\n```\n\n## Language Support\n\n- [x] JavaScript/TypeScript: `.js`, `.ts`, `.jsx`, `.tsx` (auto-detected)\n- [x] Astro: `.astro`\n  - If you use Astro, add the optional peer dependency:\n\n    ```bash\n    npm i -D @astrojs/compiler\n    ```\n- [x] Vue: `.vue`\n  - Only statements in `\u003cscript\u003e` and `\u003cscript setup\u003e` is processed.\n  - **Statements in `\u003ctemplate\u003e` is not processed**.\n\n- [ ] Svelte: not yet supported. Contributions welcome!\n  - See #4 for details.\n\n## Quick Start\n\nDefine how `import.meta` should be resolved via `bindings` (the `ImportMetaBindings` shape).\n\n```ts\nimport type { Options } from \"unplugin-transform-import-meta\"\n\n// shared bindings (TypeScript for clarity)\nconst options: Options = {\n  bindings: {\n    values: {\n      APP_NAME: \"my-app\",\n      APP_ENV: \"production\",\n      FEATURE_FLAG: true,\n    },\n    functions: {\n      version: (v) =\u003e `v${v}`,\n      asset: (path) =\u003e `/static/${path}`,\n    },\n  },\n};\n```\n\n\u003cdetails\u003e\n\u003csummary\u003eVite\u003c/summary\u003e\u003cbr\u003e\n\n```ts\n// vite.config.ts\nimport { defineConfig } from 'vite'\nimport TransformImportMeta from 'unplugin-transform-import-meta/vite'\n\nexport default defineConfig({\n  plugins: [\n    TransformImportMeta(options),\n  ],\n})\n```\n\n\u003cbr\u003e\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eRollup\u003c/summary\u003e\u003cbr\u003e\n\n```ts\n// rollup.config.ts\nimport TransformImportMeta from 'unplugin-transform-import-meta/rollup'\n\nexport default {\n  plugins: [TransformImportMeta(options)],\n}\n```\n\n\u003cbr\u003e\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eRolldown\u003c/summary\u003e\u003cbr\u003e\n\n```ts\n// rolldown.config.ts\nimport TransformImportMeta from 'unplugin-transform-import-meta/rolldown'\n\nexport default {\n  plugins: [TransformImportMeta(options)],\n}\n```\n\n\u003cbr\u003e\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eWebpack\u003c/summary\u003e\u003cbr\u003e\n\n```ts\n// webpack.config.ts\nimport TransformImportMeta from 'unplugin-transform-import-meta/webpack'\n\nexport default {\n  plugins: [TransformImportMeta(options)],\n}\n```\n\n\u003cbr\u003e\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eRspack\u003c/summary\u003e\u003cbr\u003e\n\n```ts\n// rspack.config.ts\nimport TransformImportMeta from 'unplugin-transform-import-meta/rspack'\n\nexport default {\n  plugins: [TransformImportMeta(options)],\n}\n```\n\n\u003cbr\u003e\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eesbuild\u003c/summary\u003e\u003cbr\u003e\n\n```ts\nimport { build } from 'esbuild'\nimport TransformImportMeta from 'unplugin-transform-import-meta/esbuild'\n\nawait build({\n  plugins: [TransformImportMeta(options)],\n})\n```\n\n\u003cbr\u003e\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eFarm\u003c/summary\u003e\u003cbr\u003e\n\n```ts\n// farm.config.ts\nimport TransformImportMeta from 'unplugin-transform-import-meta/farm'\n\nexport default {\n  plugins: [TransformImportMeta(options)],\n}\n```\n\n\u003cbr\u003e\u003c/details\u003e\n\n## What It Does (Before ➜ After)\n\nGiven this source code:\n\n```ts\n// input.ts\nconsole.log(import.meta.APP_NAME)\nconsole.log(import.meta.APP_ENV)\nconsole.log(import.meta.version('1.2.3'))\nconsole.log(import.meta.asset('logo.svg'))\n```\n\nIt becomes:\n\n```ts\nconsole.log(\"my-app\")\nconsole.log(\"production\")\nconsole.log(\"v1.2.3\")\nconsole.log(\"/static/logo.svg\")\n```\n\nIn `.astro` files, the plugin transforms in all contexts:\n\n- Frontmatter `--- ... ---`\n- `\u003cscript\u003e` blocks\n- Template expressions like `{import.meta.APP_NAME}`\n\n## Options\n\n```ts\nimport type { Options } from 'unplugin-transform-import-meta'\n\nconst plugin = TransformImportMeta({\n  enforce: 'pre',\n  include: [/\\.[cm]?[jt]sx?$/, /\\.astro$/],\n  exclude: [/node_modules/],\n  bindings: {\n    values: {\n      APP_NAME: 'my-app',\n      APP_ENV: 'production',\n      // key can be nested via dot-path\n      \"flags.FOO_RELEASED\": true,\n    },\n    functions: {\n      // args must be literals; non-literals are passed as null\n      version: (v) =\u003e `v${v}`,\n    },\n  },\n} satisfies Options)\n```\n\n- `enforce`: `'pre' | 'post'` (default: `'pre'`)\n  - Changing `enforce` casually can break the plugin's behavior due to\n    transform ordering across plugins and the bundler.\n  - Only change it if you\n    know exactly what you're doing and need to coordinate ordering with other\n    transforms. The default `'pre'` is recommended for most setups.\n- `include` / `exclude`: Any `unplugin-utils` FilterPattern. Defaults process JS/TS and `.astro`, excluding `node_modules`.\n- `bindings.values`: Map `import.meta.\u003cdot.path\u003e` to a literal value.\n- `bindings.functions`: Map `import.meta.\u003cmethod\u003e` to a function returning a literal.\n\nNotes:\n\n- Only literal values are inlined. Method arguments that are not literals are passed as `null` to your function.\n- Source maps are not generated by this plugin (returns `map: null`).\n\n## Reserved Keys Safety\n\nThis plugin validates and throws early if your rules override reserved `import.meta.*` keys.\n\n- WinterTC registry: please refer to \u003chttps://github.com/WinterTC55/import-meta-registry\u003e for the canonical list. If new keys are added and our list lags behind, open a PR to update it here.\n- For bundler-specific reservations, we intentionally avoid duplicating lists in this README to prevent drift. See the implementation at `src/core/reserved.ts` for the authoritative, up‑to‑date checks.\n\nWhen a conflict is detected, you will get an error like:\n\n```\nThe property name \"import.meta.\u003cname\u003e\" is reserved and cannot be used.\n```\n\nRename your property/method to a non-reserved name.\n\n## Runtime \u0026 Build Matrix\n\n- Supported bundlers: Vite, Rollup, Rolldown, Webpack, Rspack, esbuild, Farm\n- Languages: JS/TS/JSX/TSX and Astro\n- ESM-only package; use modern toolchains\n\n## License\n\n[MIT](./LICENSE) License © 2025-PRESENT [sushichan044](https://github.com/sushichan044)\n\n\u003c!-- Badges --\u003e\n\n[npm-version-src]: https://img.shields.io/npm/v/unplugin-transform-import-meta.svg\n[npm-version-href]: https://npmjs.com/package/unplugin-transform-import-meta\n[npm-downloads-src]: https://img.shields.io/npm/dm/unplugin-transform-import-meta\n[npm-downloads-href]: https://www.npmcharts.com/compare/unplugin-transform-import-meta?interval=30\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsushichan044%2Funplugin-transform-import-meta","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsushichan044%2Funplugin-transform-import-meta","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsushichan044%2Funplugin-transform-import-meta/lists"}