![\"Instagram\"](\"https://shields.io/badge/INSTAGRAM-303030?logo=instagram&style=for-the-badge&labelColor=2c488c&logoColor=white\"){kind=icon}
\n \n \n @baginskicosta/bunpack\n\n Modern bundling for TypeScript and JavaScript libraries,\n powered by Bun.\n
\n\n\n\n\n## Introduction\n\n`@baginskicosta/bunpack` is a bundler designed for libraries written\nin **TypeScript** and **JavaScript**, build on top of the native\ncapabilities provided by the [Bun][ex_bun] runtime.\n\nIt uses the `Bun.build` API to transpilate, bundle, and minify complete\nprojects for production environment while supporting both **ESM**\nand **CJS** module formats. The bundler also allows the target runtime\nto be explicitly defined, supporting environments such as\n[Node][ex_node] as well as [Bun][ex_bun].\n\nThe project is designed to provide a predictable build process for\nlibraries, with support for multiple entry points, independent module\nformats, declaration generation, and automatic package export\nconfiguration.\n\n\n\n## Features\n\n- Native bundling powered by `Bun.build`.\n- Support for TypeScript and JavaScript libraries.\n- Support for both `ESM` and `CJS` module formats.\n- Configurable target runtime for [Node][ex_node] and [Bun][ex_bun].\n- Multiple library entry points.\n- Automatic generation of package `exports`.\n- TypeScript declaration generation.\n- Optional code splitting.\n- Configurable external package handling.\n- Automatic output directory cleanup.\n- Production-oriented minification.\n- JSON-based project configuration.\n- Designed for libraries and monorepositories.\n- Minimal configuration required to get started.\n\n\n\n## Performance\n\n`@baginskicosta/bunpack` is designed around the native build\ncapabilities of [Bun][ex_bun].\n\nBecause the building process relies on [Bun's][ex_bun] native\nimplementation, the library benefits from the performance\ncharacteristics of its underlying toolchain, which is primarily\nimplemented in [Rust][ex_rust].\n\nThis makes the bundler suitable for both small standalone libraries\nand larger projects containing multiple packages or entry points.\n\n\n\n## Installation\n\n```bash\nbun add @baginskicosta/bunpack # bun package manager\n```\n\n\n\n## Basic Usage\n\nBefore using `@baginskicosta/bunpack`, you need a TypeScript or\nJavaScript library porject. If you are starting a new project\nwith [Bun][ex_bun], you can create a minimal TypeScript library with:\n\n```bash\nbun init --minimal . # creates minimal typescript library\n```\n\nIf you already have a existing TypeScript library, you can simply\ncontinue with the configuration process.\n\n### Defining the Configuration\n\n`@baginskicosta/bunpack` uses a `bunpack.json` file located at the\nroot of the project.\\\nThe configuration file follows the [Bunpack Schema](./schema.json),\nwhich provides editor support and validation for the available\nconfiguration properties.\n\nA minimal configuration can be created as follow:\n\n```json\n{\n \"$schema\": \"https://raw.githubusercontent.com/baginskicosta/bunpack/main/schema.json\"\n}\n```\n\nThe following properties are available:\n\n- `$schema`: Defines the path or URL to the\n [Bunpack Schema](./schema.json).\n- `outdir`: Defines the directory where generated files are written.\n Defaults to `\"dist\"`.\n- `rootdir`: Defines the directory containing the source code.\n Defaults to `\"source\"`.\n- `target`: Defines the runtime targeted by the generated bundle.\n Defaults to `\"bun\"`.\n- `minify`: Defines whether generated files should be minified.\n Defaults to `true`. This value is always treated as `true` when\n `NODE_ENV` is set to `\"production\"`.\n- `sourcemap`: Defines the source map generation strategy.\n Defaults to `\"none\"`.\n- `splitting`: Defines whether code splitting should be enabled.\n Defaults to `false`.\n- `packages`: Defines how external dependencies should be handled.\n Defaults to `\"bundle\"`.\n- `clean`: Defines whether the output directory should be cleaned\n before each build. Defaults to `true`.\n- `formats`: Defines configuration for each supported module format,\n including `esm` and `cjs`.\n- `entries`: Defines the library entry points. Each entry can generate\n a corresponding `exports` condition in the package's `package.json`.\n- `declarations`: Defines how TypeScript declaration files should be\n generated.\n\n## Basic Configuration\n\nThe following configuration provides a recommended setup for libraries\nthat need to support both `ESM` and `CJS` across multiple runtimes:\n\n```json\n{\n \"$schema\": \"https://raw.githubusercontent.com/baginskicosta/bunpack/main/schema.json\",\n \"outdir\": \"dist\",\n \"rootdir\": \"source\",\n \"target\": \"node\",\n \"minify\": true,\n \"sourcemap\": \"none\",\n \"splitting\": false,\n \"packages\": \"bundle\",\n \"clean\": true,\n \"formats\": {\n \"esm\": {\n \"enabled\": true,\n \"directory\": \"esm\",\n \"extension\": \".js\"\n },\n \"cjs\": {\n \"enabled\": true,\n \"directory\": \"cjs\",\n \"extension\": \".cjs\"\n }\n },\n \"entries\": [\n {\n \"name\": \"core\",\n \"entrypoint\": \"index.ts\",\n \"default\": true\n }\n ],\n \"declarations\": {\n \"enabled\": true,\n \"directory\": \"types\",\n \"tsconfig\": \"./tsconfig.build.json\"\n }\n}\n```\n\nIn this configuration, the library source code is located inside the\n`source` directory and all generated files are written to `dist`.\n\nBoth supported module formats are enabled. The resulting build will\ncontain an `ESM` version using the `.js` extension and a `CJS` version\nusing the `.cjs` extension.\n\nTypeScript declaration generation is also enabled. Declaration files\nare written to the `types` directory inside `dist` and use the\n`.d.ts` extension.\n\nThe `target` is configured as `\"node\"`, which is recommended for most\nlibraries intended to be consumed by different JavaScript runtimes.\n\n### Defining Entry Points\n\nThe `entries` property defines the modules exposed by the library.\\\nEach entry contains:\n\n- `name`: Identifies the entry point.\n- `entrypoint`: Defines the source file used as the entry point.\n- `default`: Determines whether the entry represents the package's\n default export.\n\nFor a library containing only one entry point, that entry must be\nmarked as the default:\n\n```json\n{\n \"entries\": [\n {\n \"name\": \"core\",\n \"entrypoint\": \"index.ts\",\n \"default\": true\n }\n ]\n}\n```\n\nWhen a library contains multiple entry points, exactly one entry must\nbe marked as the default:\n\n```json\n{\n \"entries\": [\n {\n \"name\": \"core\",\n \"entrypoint\": \"index.ts\",\n \"default\": true\n },\n {\n \"name\": \"extras\",\n \"entrypoint\": \"extras/index.ts\",\n \"default\": false\n }\n ]\n}\n```\n\nIn this example, the library exposes two independent modules:\n`core` and `extras`.\n\nThe default entry represents the package root and is therefore\navailable through `\".\"`.\\\nAdditional entries are exposed through their respective subpaths.\n\nThe resulting `exports` configuration in `package.json` is equivalent\nto:\n\n```json\n{\n \"exports\": {\n \".\": {\n \"types\": \"./dist/types/index.d.ts\",\n \"import\": \"./dist/esm/index.js\",\n \"require\": \"./dist/cjs/index.cjs\"\n },\n \"./extras\": {\n \"types\": \"./dist/types/extras/index.d.ts\",\n \"import\": \"./dist/esm/extras/index.js\",\n \"require\": \"./dist/cjs/extras/index.cjs\"\n }\n }\n}\n```\n\nThe `name` property of the default entry is ignored when generating\nthe package root export.\\\nAs a convention, we recommend naming the default entry `\"core\"` to\nmake its purpose explicit.\n\n### Entry Point Rules\n\nThe `entries` configuration follows a small set of rules:\n\n- A library with a single entry must define that entry as `default`.\n- A library with multiple entries must define exactly one default\n entry.\n- Defining multiple default entries results in an error.\n- Omitting the default entry when multiple entries are defined results\n in an error.\n- The default entry is mapped to the package root (`\".\"`).\n- Non-default entries are exposed as package subpaths.\n\nThese rules ensure that the generated `exports` configuration remains\nunambiguous and predictable.\n\n\n\n## Runtime Target\n\nThe `target` property determines which JavaScript runtime the generated\nbundle is intended to run on.\\\n`@baginskicosta/bunpack` currently supports:\n\n```json\n{\n \"target\": \"node\"\n}\n```\n\nand:\n\n```json\n{\n \"target\": \"bun\"\n}\n```\n\nFor most libraries, we recommend using:\n\n```json\n{\n \"target\": \"node\"\n}\n```\n\nThis provides a more general-purpose output suitable for libraries\nthat may be consumed by different JavaScript environments.\nIf the library or tool is specifically designed for [Bun][ex_bun],\nthe target can instead be configured as:\n\n```json\n{\n \"target\": \"bun\"\n}\n```\n\nThe `bun` target should generally be preferred when the package is\nintended exclusively, or primarily, for Bun-based environments.\n\n\n\n## Module Formats\n\nThe `formats` property controls which module formats are generated.\\\nThe bundler currently supports:\n\n- `esm`: Generates ECMAScript modules.\n- `cjs`: Generates CommonJS modules.\n\nEach format can be independently configured:\n\n```json\n{\n \"formats\": {\n \"esm\": {\n \"enabled\": true,\n \"directory\": \"esm\",\n \"extension\": \".js\"\n },\n \"cjs\": {\n \"enabled\": true,\n \"directory\": \"cjs\",\n \"extension\": \".cjs\"\n }\n }\n}\n```\n\nThis allows libraries to expose the same API through both modern\n`import` syntax and CommonJS `require` syntax.\n\n\n\n## TypeScript Declarations\n\nThe `declarations` property controls the generation of TypeScript\ndeclaration files.\n\nA typical configuration is:\n\n```json\n{\n \"declarations\": {\n \"enabled\": true,\n \"directory\": \"types\",\n \"tsconfig\": \"./tsconfig.build.json\"\n }\n}\n```\n\nThe `tsconfig` property specifies the TypeScript configuration used\nwhen analyzing the project source and generating declaration files.\n\nThe build configuration can extend the project's main `tsconfig.json`\nwhile defining only the files and directories that should be included\nor excluded from the declaration build.\n\nFor example:\n\n```json\n{\n \"extends\": \"./tsconfig.json\",\n \"include\": [\"source/**/*.ts\"],\n \"exclude\": [\"node_modules\", \"dist\", \"**/*.test.ts\", \"**/*.spec.ts\"]\n}\n```\n\nIn this configuration, `tsconfig.build.json` inherits the project's\nbase TypeScript configuration and only defines the source files that\nshould participate in the build.\n\nThe `include` property specifies the source files that should be\nanalyzed, while `exclude` prevents files and directories that should\nnot be part of the library build from being considered.\n\nThe actual declaration output is controlled by the `declarations`\nconfiguration in `bunpack.json`. This allows the TypeScript build\nconfiguration to remain focused on describing the project's source\nboundaries without duplicating output-related compiler options.\n\nThe generated declaration files can use different extensions when\nrequired by the target module system, including `.d.ts` and `.d.cts`.\n\n\n\n## Building the Library\n\nAfter installing the package and configuring `bunpack.json`, the\nlibrary can be compiled by invoking the CLI from the root directory\nof the project.\n\nUsing [Bun][ex_bun]:\n\n```bash\nbun bunpack\n```\n\nAlternatively, you can execute the CLI through `bunx`:\n\n```bash\nbunx bunpack\n```\n\nIf the build completes successfully, all generated files will be\nwritten to the directory configured through `outdir`.\\\nFor example, with:\n\n```json\n{\n \"outdir\": \"dist\"\n}\n```\n\nthe generated library will be available inside:\n\n```text\ndist/\n```\n\nThe final structure depends on the configured module formats, entry\npoints, and declaration settings.\n\n\n\n## Support My Work\n\nIf this this project, or any of my other projects, has been useful to\nyou, your team, or your company, consider supporting my work.\nMaintaining open-source projects take time. Support helps me keep\nworking on improvements, fixes, documentation, and new features while\ncontinuing to make projects available to everyone.\n\nIf you would like to directly support the development of my projects,\ntou can become a supported on Patreon:\n\n[![Sponsor on Patreon][badge_patreon]][me_patreon]\n\nEven a small contribution helps. It gives me more time to work on\nopen-source projects and keep them maintained instead of having to\ntreat them as something I can only work on in my spare time.\n\n### Follow My Work\n\nYou can also follow me on social media. This is another simple way to\nsupport my work, keep up with new projects and content, and help more\ndevelopers discover what I am building.\n\n[![Follow on YouTube][badge_youtube]][me_youtube]\n[![Follow on Instagram][badge_insta]][me_insta]\n[![Follow on Twitch][badge_twitch]][me_twitch]\n\n\n\n## Supporters\n\n> Want to support the development of open-source projects?\\\n> Become a [supporter on Patreon][me_patreon] and have your name or\n> company featured in this and future repositories and projects.\n\nI want to sincerely thank everyone who supports my work through\n[Patreon][me_patreon]. Your support gives me the time and motivation\nto keep building, maintaining, and improving these projects.\n\nThank you for supporting my work and helping me keep open-source\ndevelopment moving forward.\n","readmeFilename":"README.md"}