SmartBundle

Build your library for any JavaScript environment without the complexity

Install SmartBundle as a development dependency with your project's package manager:

npm install --save-dev smartbundle

Add a build script and the package entrypoints and assets you intend to publish:

{
  // Your package name
  name: "my-package",
  // Package version
  version: "1.0.0",
  // Must be true to avoid accidental publishing
  private: true,
  // SmartBundle supports only ES modules
  type: "module",
  // Copy these files to the package without preprocessing
  files: ["skills/**", "docs/**/*.md"],
  // Entry point used by SmartBundle
  exports: {
    ".": "./src/index.js",
    // Raw exports can be resolved by package consumers
    "./skill": "./skills/SKILL.md",
  },
  scripts: {
    // Run this to build your package
    build: "smartbundle build",
  },
}

smartbundle build validates the package configuration and builds it into ./dist. Run it through the package script:

npm run build

If the build fails, fix the configuration, dependency, or source file identified by the error and run the build again. Repeat until it succeeds. The built files, including an automatically generated package.json, will be in ./dist.

See the package.json guide for a full explanation of each field. TypeScript projects should also consult the TypeScript guide.

• Zero Configuration - Point to your entry file and build
• Universal Output - ESM and CommonJS bundles generated automatically
• TypeScript Ready - Full TypeScript support with type definitions
• Raw Files - Copy documentation, skills, schemas, and other assets without preprocessing
• React Support - Automatic JSX transformations for modern and legacy modes
• Developer Friendly - Source maps included for better debugging
• Broad Compatibility - Works with Node.js, Webpack, Vite, Rollup, Bun, and more

SmartBundle is guaranteed to work on all active and maintenance LTS releases, plus the current release. Former LTS versions that have reached end-of-life remain supported on a best-effort basis. Every bundled package is tested in real environments — from Node.js and Bun to Webpack and Metro — to ensure it just works.

Each supported combination builds the test package with the listed build version and then type-checks an isolated consumer with the listed consumer version. The matrix tests the latest release of each supported TypeScript major. TypeScript 7 builds use @typescript/typescript6 for SmartBundle's compiler API. TypeScript 7 consumers do not support the removed node10 resolution strategy.

We aim to support as many bundlers and runtimes as possible. If the bundled package doesn't work with your bundler, please let us know.

SmartBundle automatically detects and integrates with your tools - just add what you need to your project.

SmartBundle supports TypeScript 5, 6, and 7. Install TypeScript as a dev dependency and start creating .ts files:

npm install --save-dev "typescript@>=5.0.0 <8.0.0"

TypeScript 7.0 does not expose the compiler API that SmartBundle needs to generate declarations. TypeScript 7 projects must also install the official TypeScript 6 compatibility bridge:

npm install --save-dev "typescript@>=7.0.0 <8.0.0" @typescript/typescript6

SmartBundle continues to use the project's TypeScript API directly on TypeScript 5 and 6. On TypeScript 7 it uses the bridge only for declaration emit and declaration-file transforms.

Add @babel/core@^7.26.0 || ^8.0.0 as a dev dependency and create a Babel configuration file in your project root. SmartBundle will automatically apply your transformations.

Add react to your dependencies. SmartBundle automatically detects React and configures JSX transformations. Both modern and legacy modes are supported.

For detailed React configuration options, see our React guide.

SmartBundle enforces certain package.json conventions to ensure reliable builds. For detailed information about:

• Required and banned fields
• Configuration limitations
• Package.json best practices

See our package.json guide.

Please, look at the known fixable issues before creating your own one. Some bugs already have a solution but cannot be fixed without user action.

Minification is typically needed only for production. During development, readable, unminified output helps with debugging.

We prioritize keeping the node_modules size manageable and avoid unnecessary dependencies. If your package does not require TypeScript, for instance, you don’t need to install those specific tools.

If you need assistance or wish to contribute, please check out our discussion forum and issue tracker.