![](\".github/logo.webp\"){kind=logo}
\n\n\t\n
\n\t![](\"https://raw.githubusercontent.com/privatenumber/sponsors/master/banners/assets/donate.webp\")
\n\t![](\"https://raw.githubusercontent.com/privatenumber/sponsors/master/banners/assets/sponsor.webp\")
\n
Already a sponsor? Join the discussion in the Development repo!
\n\n## Install\n```sh\nnpm install --save-dev pkgroll\n```\n\n> [!NOTE]\n> TypeScript 7 does not include the compiler API needed to bundle declaration files. Install `@typescript/typescript6` alongside TypeScript 7; pkgroll uses it only for declaration bundling.\n\n## Quick setup\n1. Setup your project with source files in `src` and output in `dist` (configurable).\n\n2. Define package entry-files in `package.json`.\n\n [These configurations](https://nodejs.org/api/packages.html#package-entry-points) are for Node.js to determine how to import the package.\n\n Pkgroll leverages the same configuration to determine how to build the package.\n\n\t```json5\n\t{\n\t \"name\": \"my-package\",\n\n\t // Set \"module\" or \"commonjs\" (https://nodejs.org/api/packages.html#type)\n\t // \"type\": \"module\",\n\n\t // Define the output files\n\t \"main\": \"./dist/index.cjs\",\n\t \"module\": \"./dist/index.mjs\",\n\t \"types\": \"./dist/index.d.cts\",\n\n\t // Define output files for Node.js export maps (https://nodejs.org/api/packages.html#exports)\n\t \"exports\": {\n\t \"require\": {\n\t \"types\": \"./dist/index.d.cts\",\n\t \"default\": \"./dist/index.cjs\",\n\t },\n\t \"import\": {\n\t \"types\": \"./dist/index.d.mts\",\n\t \"default\": \"./dist/index.mjs\",\n\t },\n\t },\n\n\t // bin files will be compiled to be executable with the Node.js hashbang\n\t \"bin\": \"./dist/cli.js\",\n\n\t // (Optional) Add a build script referencing `pkgroll`\n\t \"scripts\": {\n\t \"build\": \"pkgroll\",\n\t },\n\n\t // ...\n\t}\n\t```\n\n\tPaths that start with `./dist/` are automatically mapped to files in the `./src/` directory.\n\n> [!TIP]\n> In addition to `package.json`, pkgroll also supports [pnpm's `package.yaml`](https://pnpm.io/package_json#:~:text=In%20addition%20to%20the%20traditional%20package.json%20format%2C%20pnpm%20also%20supports%20package.json5%20(via%20json5)%20and%20package.yaml%20(via%20js%2Dyaml).).\n\n3. Package roll!\n\t```sh\n\tnpm run build # or npx pkgroll\n\t```\n\n## Usage\n\n### Entry-points\n_Pkgroll_ parses package entry-points from `package.json` by reading properties `main`, `module`, `types`, and `exports`.\n\nThe paths in `./dist` are mapped to paths in `./src` (configurable with the `--srcdist` flag) to determine bundle entry-points.\n\n#### Wildcard exports\n\n_Pkgroll_ supports [wildcard patterns](https://nodejs.org/api/packages.html#subpath-patterns) in `package.json#exports` for exporting multiple modules with a single pattern:\n\n```json5\n{\n \"exports\": {\n \"./utils/*\": \"./dist/utils/*.mjs\",\n \"./components/*/index\": \"./dist/components/*/index.mjs\",\n },\n}\n```\n\nThis automatically bundles all matching source files. For example:\n- `src/utils/format.ts` → `dist/utils/format.mjs`\n- `src/components/button/index.ts` → `dist/components/button/index.mjs`\n\n> [!IMPORTANT]\n> Wildcard patterns must include a file extension (e.g., `.mjs`, `.cjs`)\n\n#### Subpath Imports\n\n_Pkgroll_ supports building entry-points defined in [`package.json#imports` (Node.js subpath imports)](https://nodejs.org/api/packages.html#subpath-imports), including conditional imports:\n\n```json\n{\n \"imports\": {\n \"#my-pkg\": \"./dist/index.js\",\n \"#env\": {\n \"node\": \"./dist/env.node.js\",\n \"default\": \"./dist/env.browser.js\"\n }\n }\n}\n```\n\n### Output formats\n_Pkgroll_ detects the format for each entry-point based on the file extension or the `package.json` property it's placed in, using the [same lookup logic as Node.js](https://nodejs.org/api/packages.html#determining-module-system).\n\n| `package.json` property | Output format |\n| - | - |\n| `main` | Auto-detect |\n| `module` | ESM\n\t\n\t\t![](\"https://cdn.jsdelivr.net/gh/privatenumber/sponsors/sponsorkit/sponsors.svg\")
\n\t\n