{"id":28751124,"url":"https://github.com/ertgl/export-map-generator","last_synced_at":"2026-01-20T17:35:04.568Z","repository":{"id":294359846,"uuid":"986733031","full_name":"ertgl/export-map-generator","owner":"ertgl","description":"Automate exports generation for multi-format packages.","archived":false,"fork":false,"pushed_at":"2025-06-13T15:19:21.000Z","size":2910,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-13T16:32:09.807Z","etag":null,"topics":["exports","javascript","package-json","typescript"],"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/ertgl.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}},"created_at":"2025-05-20T03:45:13.000Z","updated_at":"2025-06-13T15:19:18.000Z","dependencies_parsed_at":"2025-06-13T16:26:56.815Z","dependency_job_id":"48bd2168-351f-45ec-8182-f6de36021050","html_url":"https://github.com/ertgl/export-map-generator","commit_stats":null,"previous_names":["ertgl/export-map-generator"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/ertgl/export-map-generator","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ertgl%2Fexport-map-generator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ertgl%2Fexport-map-generator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ertgl%2Fexport-map-generator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ertgl%2Fexport-map-generator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ertgl","download_url":"https://codeload.github.com/ertgl/export-map-generator/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ertgl%2Fexport-map-generator/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260250005,"owners_count":22980768,"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":["exports","javascript","package-json","typescript"],"created_at":"2025-06-16T22:09:18.517Z","updated_at":"2026-01-20T17:35:04.555Z","avatar_url":"https://github.com/ertgl.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# export-map-generator\n\nAutomates the `exports` field in `package.json` for multi-format packages by\nanalyzing distribution files. Declarative, extensible, and build-tool agnostic.\n\n## Table of Contents\n\n- [Overview](#overview)\n  - [Features](#features)\n- [Installation](#installation)\n  - [Optional Peer Dependencies](#optional-peer-dependencies)\n- [Usage](#usage)\n  - [CLI Usage](#cli-usage)\n  - [Programmatic API](#programmatic-api)\n- [Configuration](#configuration)\n- [Extensions](#extensions)\n- [Presets](#presets)\n  - [CJS Preset](#cjs-preset)\n  - [CSS Preset](#css-preset)\n  - [DTS Preset](#dts-preset)\n  - [ESM Preset](#esm-preset)\n  - [Generic Preset](#generic-preset)\n  - [JSON Preset](#json-preset)\n  - [Package-JSON Preset](#package-json-preset)\n  - [Standard Preset](#standard-preset)\n- [Practical Example](#practical-example)\n- [License](#license)\n\n## Overview\n\n`export-map-generator` provides a plugin-oriented pipeline for full control\nover the generation of the exports -typically for `package.json` files-\nallowing developers to customize, extend, or override every step of the process.\n\n### Features\n\nThe generator is built around several core ideas, all designed to enhance the\ndeveloper experience.\n\n#### Convention-first, plugin-friendly\n\nStart with presets, extend or override as needed. From file-system API to entry\ngeneration, every step is customizable.\n\n\u003cdetails open\u003e\n  \u003csummary\u003e\n    \u003cb\u003e\n      Demonstration: Configuration with the built-in presets\n    \u003c/b\u003e\n  \u003c/summary\u003e\n\n  ```ts\n  export default defineConfig({\n    presets: [\n      dts(),\n      cjs(),\n      esm(),\n      standard(),\n    ],\n  });\n  ```\n\u003c/details\u003e\n\n#### Output-driven\n\nScans the distribution folders instead of the source files. This ensures that\nthe actual distribution files are used for generating the exports, causing zero\nextra I/O overhead for the task.\n\n\u003cdetails\u003e\n  \u003csummary\u003e\n    \u003cb\u003e\n      Demonstration: Tree structure of a sample distribution folder\n    \u003c/b\u003e\n  \u003c/summary\u003e\n\n  ```text\n  dist\n    ├── cjs\n    │   └── array.cjs\n    ├── esm\n    │   └── array.mjs\n    └── types\n        └── array.d.ts\n  ```\n\u003c/details\u003e\n\n#### Precise entry-point resolution\n\nSupports CJS, ESM, DTS, hybrid modules, and more. The import conditions are\norganized in the correct order to prevent conflicts.\n\n\u003cdetails\u003e\n  \u003csummary\u003e\n    \u003cb\u003e\n      Demonstration: Exports generated for a sample dual-package module\n    \u003c/b\u003e\n  \u003c/summary\u003e\n\n  ```json\n  {\n    \"exports\": {\n      \"./array.js\": {\n        \"types\": \"./dist/types/array.d.ts\",\n        \"import\": \"./dist/esm/array.mjs\",\n        \"require\": \"./dist/cjs/array.cjs\",\n        \"default\": \"./src/array.ts\"\n      }\n    }\n  }\n  ```\n\u003c/details\u003e\n\n#### Path ambiguity resolution\n\nResolves path ambiguities by organizing the exported entries in the correct\norder to prevent overlapping import paths.\n\n\u003cdetails\u003e\n  \u003csummary\u003e\n    \u003cb\u003e\n      Demonstration: Multiple import paths generated for the same file\n    \u003c/b\u003e\n  \u003c/summary\u003e\n\n  ```json\n  {\n    \"exports\": {\n      \"./array.d.ts\": {\n        \"types\": \"./dist/types/array.d.ts\",\n        \"default\": \"./src/array.ts\"\n      },\n      \"./array.js\": {\n        \"types\": \"./dist/types/array.d.ts\",\n        \"import\": \"./dist/esm/array.mjs\",\n        \"require\": \"./dist/cjs/array.cjs\",\n        \"default\": \"./src/array.ts\"\n      },\n      \"./array\": {\n        \"types\": \"./dist/types/array.d.ts\",\n        \"import\": \"./dist/esm/array.mjs\",\n        \"require\": \"./dist/cjs/array.cjs\",\n        \"default\": \"./src/array.ts\"\n      }\n    }\n  }\n  ```\n\u003c/details\u003e\n\n#### Built-in support for barrel files\n\nDetects and generates exports for barrel files (index files) in the root and\nsubdirectories.\n\n\u003cdetails\u003e\n  \u003csummary\u003e\n    \u003cb\u003e\n      Demonstration: Generating exports from directories\n    \u003c/b\u003e\n  \u003c/summary\u003e\n\n  ```ts\n  export default defineConfig({\n    extensions: [\n      barrel(),\n    ],\n  });\n  ```\n\n  ```json\n  {\n    \"exports\": {\n      \"./index.js\": {\n        \"types\": \"./dist/types/index.d.ts\",\n        \"import\": \"./dist/esm/index.mjs\",\n        \"require\": \"./dist/cjs/index.cjs\",\n        \"default\": \"./src/index.ts\"\n      },\n      \".\": {\n        \"types\": \"./dist/types/index.d.ts\",\n        \"import\": \"./dist/esm/index.mjs\",\n        \"require\": \"./dist/cjs/index.cjs\",\n        \"default\": \"./src/index.ts\"\n      }\n    }\n  }\n  ```\n\u003c/details\u003e\n\n#### CLI or programmatic API\n\nUse via terminal or integrate into custom flows.\n\n\u003cdetails\u003e\n  \u003csummary\u003e\n    \u003cb\u003e\n      Demonstration: Generating the export map programmatically\n    \u003c/b\u003e\n  \u003c/summary\u003e\n\n  ```ts\n  const context = await resolveContext();\n  const exportMap = await generateExportMapByContext(context);\n  ```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003e\n    \u003cb\u003e\n      Demonstration: Listing the CLI commands\n    \u003c/b\u003e\n  \u003c/summary\u003e\n\n  ```sh\n  ⋊\u003e export-map-generator\n  Usage: export-map-generator [options] [command]\n\n  Options:\n    -V, --version        output the version number\n    --cwd \u003cPATH\u003e         path to the working directory\n    -c, --config \u003cPATH\u003e  path to the configuration file\n    --dry-run            preview changes without writing to disk (default: false)\n    -h, --help           display help for command\n\n  Commands:\n    config               configuration commands\n    context              context commands\n    generate [options]   generate export map\n    help [command]       display help for command\n  ```\n\u003c/details\u003e\n\n## Installation\n\nThe package is available on npm and can be installed with any compatible\npackage manager.\n\n```sh\nnpm install --save-dev export-map-generator\n```\n\n### Optional Peer Dependencies\n\nThe library uses several optional peer dependencies to provide additional\nfunctionality. If you encounter issues with loading the configuration or\nrunning the CLI commands, you may need to install these dependencies.\n\n```sh\nnpm install --save-dev commander cosmiconfig pretty-format\n```\n\n## Usage\n\nBy default, the generator does not include any activated functionality. This\ndesign ensures that the export strategy remains explicit and intentional. From\nanalyzing directories to writing the final export map, all logic is handled via\nextensions and presets that are explicitly activated in the configuration.\n\nBuilt-in presets can be used to quickly setup the generator with common export\npatterns and conventions. For the list of available presets, refer to the\n[Presets](#presets) section.\n\n### CLI Usage\n\nThe CLI provides a convenient way to interact with the generator. You can\nuse it to generate the export map, preview changes, and inspect the context.\n\nTo preview the changes without writing to disk, you can use the `--dry-run` and\n`--stdout` options together:\n\n```sh\nexport-map-generator --dry-run generate --stdout\n```\n\n**Note:** The `--stdout` option does not prevent the generator from updating the\n`package.json` file. To achieve that, you need to use the `--dry-run` option.\n\n### Programmatic API\n\nFor programmatic usage, you can import the library and use it in your scripts:\n\n```ts\nimport { resolveContext } from \"export-map-generator/context\";\nimport { generateExportMapByContext } from \"export-map-generator/export-map\";\n\nconst context = await resolveContext({ dryRun: true });\nconst exportMap = await generateExportMapByContext(context);\n```\n\n## Configuration\n\nThe generator without any configuration cannot generate an `exports` map,\nthis is by design to ensure that the user explicitly defines how the exports\nshould be structured. The configuration allows you to specify presets, plugins,\nand other options to customize the export map generation process.\n\nThe configuration for `export-map-generator` can be done via these files:\n\n- `exports.config.cjs`\n- `exports.config.js`\n- `exports.config.mjs` (recommended)\n- `exports.config.ts` (recommended)\n\nThe configuration file should export either a default object or a function that\nreturns an object.\n\n```ts\nimport defineConfig from \"export-map-generator/config\";\n\nexport default defineConfig({});\n```\n\n## Extensions\n\nExtensions are the plugins that provide core or additional functionalities to\nthe generator. An extension can implement any method listed in the table below.\n\n\u003ctable\u003e\n  \u003cthead\u003e\n    \u003ctr\u003e\n      \u003cth\u003eMethod\u003c/th\u003e\n      \u003cth\u003eDescription\u003c/th\u003e\n    \u003c/tr\u003e\n  \u003c/thead\u003e\n  \u003ctbody\u003e\n    \u003ctr\u003e\n      \u003ctd\u003esetup\u003c/td\u003e\n      \u003ctd\u003eInitialize the extension and set up any necessary state.\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd\u003eresolveConfig\u003c/td\u003e\n      \u003ctd\u003eResolve the configuration for the extension.\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd\u003eresolveContext\u003c/td\u003e\n      \u003ctd\u003eResolve the context for the extension.\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd\u003eproduceDirentRefs\u003c/td\u003e\n      \u003ctd\u003eProduce directory entries (e.g. matching a pattern).\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd\u003eproduceEntriesByDirentRef\u003c/td\u003e\n      \u003ctd\u003eProduce export-map entries based on the given directory entry.\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd\u003eproduceEntries\u003c/td\u003e\n      \u003ctd\u003eProduce export-map entries, (e.g. additional entries).\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd\u003ehandleEntryByDirentRef\u003c/td\u003e\n      \u003ctd\u003eHandle the entry by directory entry.\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd\u003ehandleEntry\u003c/td\u003e\n      \u003ctd\u003eHandle the entry (any entry).\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd\u003eaggregateExportMap\u003c/td\u003e\n      \u003ctd\u003e\n        Consolidate the generated entries and produce the final export map.\n      \u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd\u003esortExportMap\u003c/td\u003e\n      \u003ctd\u003eSort the export map entries (e.g. to avoid conflicts).\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd\u003ereportExportMap\u003c/td\u003e\n      \u003ctd\u003e\n        Report the generated export map (e.g. update the package.json file).\n      \u003c/td\u003e\n    \u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e\n\n## Presets\n\nPresets are predefined configurations that encapsulate common export patterns\nand conventions. They can be used to quickly set up the export map generation\nwithout needing to define everything from scratch. The library comes with a\nset of built-in presets that can be used directly or extended as needed.\n\n### CJS Preset\n\nThe CJS preset is designed for projects that distribute their code using the\nCommonJS module format.\n\n\u003cdetails\u003e\n  \u003csummary\u003e\n    \u003cb\u003e\n      Example: Using the CJS preset\n    \u003c/b\u003e\n  \u003c/summary\u003e\n\n  ```ts\n  import defineConfig from \"export-map-generator/config\";\n  import cjs from \"export-map-generator/presets/cjs\";\n\n  export default defineConfig({\n    presets: [\n      cjs(),\n    ],\n  });\n  ```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003e\n    \u003cb\u003e\n      Example: Using the CJS preset for TypeScript source files\n    \u003c/b\u003e\n  \u003c/summary\u003e\n\n  ```ts\n  import defineConfig from \"export-map-generator/config\";\n  import cjs from \"export-map-generator/presets/cjs\";\n\n  export default defineConfig({\n    presets: [\n      cjs({\n        src: {\n          extension: \".ts\",\n        },\n      }),\n    ],\n  });\n  ```\n\u003c/details\u003e\n\n### CSS Preset\n\nThe CSS preset is designed for distributing stylesheet files.\n\n\u003cdetails\u003e\n  \u003csummary\u003e\n    \u003cb\u003e\n      Example: Using the CSS preset\n    \u003c/b\u003e\n  \u003c/summary\u003e\n\n  ```ts\n  import defineConfig from \"export-map-generator/config\";\n  import css from \"export-map-generator/presets/css\";\n\n  export default defineConfig({\n    presets: [\n      css(),\n    ],\n  });\n  ```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003e\n    \u003cb\u003e\n      Example: Using the CSS preset for Sass source files\n    \u003c/b\u003e\n  \u003c/summary\u003e\n\n  ```ts\n  import defineConfig from \"export-map-generator/config\";\n  import css from \"export-map-generator/presets/css\";\n\n  export default defineConfig({\n    presets: [\n      css({\n        src: {\n          extension: \".sass\",\n        },\n      }),\n    ],\n  });\n  ```\n\u003c/details\u003e\n\n### DTS Preset\n\nThe DTS preset is designed for projects that distribute TypeScript declaration\nfiles.\n\n\u003cdetails\u003e\n  \u003csummary\u003e\n    \u003cb\u003e\n      Example: Using the DTS preset\n    \u003c/b\u003e\n  \u003c/summary\u003e\n\n  ```ts\n  import defineConfig from \"export-map-generator/config\";\n  import dts from \"export-map-generator/presets/dts\";\n\n  export default defineConfig({\n    presets: [\n      dts(),\n    ],\n  });\n  ```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003e\n    \u003cb\u003e\n      Example: Using the DTS preset for TypeScript source files\n    \u003c/b\u003e\n  \u003c/summary\u003e\n\n  ```ts\n  import defineConfig from \"export-map-generator/config\";\n  import dts from \"export-map-generator/presets/dts\";\n\n  export default defineConfig({\n    presets: [\n      dts({\n        src: {\n          extension: \".ts\",\n        },\n      }),\n    ],\n  });\n  ```\n\u003c/details\u003e\n\n### ESM Preset\n\nThe ESM preset is designed for projects that distribute their code using the\nECMAScript module format.\n\n\u003cdetails\u003e\n  \u003csummary\u003e\n    \u003cb\u003e\n      Example: Using the ESM preset\n    \u003c/b\u003e\n  \u003c/summary\u003e\n\n  ```ts\n  import defineConfig from \"export-map-generator/config\";\n  import esm from \"export-map-generator/presets/esm\";\n\n  export default defineConfig({\n    presets: [\n      esm(),\n    ],\n  });\n  ```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003e\n    \u003cb\u003e\n      Example: Using the ESM preset for TypeScript source files\n    \u003c/b\u003e\n  \u003c/summary\u003e\n\n  ```ts\n  import defineConfig from \"export-map-generator/config\";\n  import esm from \"export-map-generator/presets/esm\";\n\n  export default defineConfig({\n    presets: [\n      esm({\n        src: {\n          extension: \".ts\",\n        },\n      }),\n    ],\n  });\n  ```\n\u003c/details\u003e\n\n### Generic Preset\n\nThe generic preset is designed to provide a flexible configuration for projects\nthat do not fit into the standard module formats. It allows defining custom\nexport patterns and conventions.\n\n\u003cdetails\u003e\n  \u003csummary\u003e\n    \u003cb\u003e\n      Example: Using the generic preset for arbitrary files\n    \u003c/b\u003e\n  \u003c/summary\u003e\n\n  ```ts\n  import defineConfig from \"export-map-generator/config\";\n  import generic from \"export-map-generator/presets/generic\";\n\n  export default defineConfig({\n    presets: [\n      generic({\n        conditions: [\n          \"license\",\n        ],\n        dist: {\n          path: \"licenses\",\n          extension: \"\",\n        },\n        filter: (direntRef) =\u003e\n        {\n          return (\n            direntRef.dirent.isFile()\n            \u0026\u0026 [\"\", \".md\", \".txt\"].includes(direntRef.parsedPath.ext)\n          );\n        },\n        virtual: {\n          extension: \".license\"\n        },\n      }),\n    ],\n  });\n  ```\n\u003c/details\u003e\n\n### JSON Preset\n\nThe JSON preset is designed for distributing JSON files.\n\n\u003cdetails\u003e\n  \u003csummary\u003e\n    \u003cb\u003e\n      Example: Using the JSON preset\n    \u003c/b\u003e\n  \u003c/summary\u003e\n\n  ```ts\n  import defineConfig from \"export-map-generator/config\";\n  import json from \"export-map-generator/presets/json\";\n\n  export default defineConfig({\n    presets: [\n      json(),\n    ],\n  });\n  ```\n\u003c/details\u003e\n\n### Package-JSON Preset\n\nThe package-json preset ensures that `package.json` file is explicitly\nspecified in the `exports`, which is required by some environments to access\nmetadata safely.\n\n\u003cdetails\u003e\n  \u003csummary\u003e\n    \u003cb\u003e\n      Example: Using the Package-JSON preset\n    \u003c/b\u003e\n  \u003c/summary\u003e\n\n  ```ts\n  import defineConfig from \"export-map-generator/config\";\n  import packageJSON from \"export-map-generator/presets/package-json\";\n\n  export default defineConfig({\n    presets: [\n      packageJSON(),\n    ],\n  });\n  ```\n\u003c/details\u003e\n\n### Standard Preset\n\nThe standard preset provides a comprehensive configuration that combines\nextensions that are responsible for these core functionalities:\n\n- Analyzing the distribution for barrel files (index files)\n- Generating exports from directories that contain barrel files\n- Consolidating the export patterns per import path\n- Preventing import path conflicts by organizing them in correct order\n- Preventing runtime condition conflicts by organizing the exports in correct order\n- Updating the `exports` field in the `package.json` file\n\n\u003cdetails\u003e\n  \u003csummary\u003e\n    \u003cb\u003e\n      Example: Using the standard preset\n    \u003c/b\u003e\n  \u003c/summary\u003e\n\n  ```ts\n  import defineConfig from \"export-map-generator/config\";\n  import standard from \"export-map-generator/presets/standard\";\n\n  export default defineConfig({\n    presets: [\n      standard(),\n    ],\n  });\n  ```\n\u003c/details\u003e\n\n## Practical Example\n\nThe work of `export-map-generator` can be seen in the\n[`package.json`](package.json) file of this repository. The `exports` field is\ngenerated based on the distribution files and the configuration provided in\nthe [`exports.config.ts`](exports.config.ts) file. The generator analyzes the\ndistribution files and generates the `exports` field based on the conventions\ndefined in the configuration.\n\n## License\n\nThis project is licensed under the\n[MIT License](https://opensource.org/license/mit).\nSee the [LICENSE](LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fertgl%2Fexport-map-generator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fertgl%2Fexport-map-generator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fertgl%2Fexport-map-generator/lists"}