UltraBundle

1.0.2 · active · verified Tue Apr 21

UltraBundle is an efficient and aggressive JavaScript/TypeScript bundler built upon Rollup, designed for projects requiring optimized output with minimal configuration. Currently at version 1.0.2, it appears to be under active development, though a specific release cadence is not explicitly stated. Its key differentiators include first-class TypeScript support, a comprehensive suite of out-of-the-box optimizations, and a straightforward single JSON file (`bundles.json`) configuration approach. Unlike more complex bundlers, it aims to simplify the bundling process by abstracting away much of the underlying Rollup configuration, providing presets for development, watching, and production builds with optimizations. This tool is intended for bundling application code, not libraries.

Common errors

```
Error: No bundles.json file found in the root directory.
```
cause The `bundles.json` configuration file is missing or not located in the project's root directory (where `package.json` resides).

fix Create a `bundles.json` file in your project's root directory, ensuring it contains a valid JSON array of bundle configurations.
```
Error: Could not resolve 'path/to/module' from 'path/to/source.ts'
```
cause A module import path could not be resolved by the bundler, typically due to incorrect relative paths, missing `node_modules` installations, or incorrect `baseUrl`/`paths` configuration in `tsconfig.json`.

fix Double-check import paths in your source code. Ensure all dependencies are correctly installed (`npm install`). Verify `tsconfig.json`'s `compilerOptions.paths` and `compilerOptions.baseUrl` are set up correctly if using path aliases.
```
TypeError: Cannot read properties of undefined (reading 'value') during build.
```
cause This generic error often indicates an issue within the Rollup configuration or a plugin, potentially caused by an invalid or unexpected input, or a problem with a specific optimization pass.

fix Review your `bundles.json` configuration for any typos or invalid properties. Try a simpler configuration first to isolate the problem. Check for recent changes in UltraBundle or Rollup that might affect your setup. Temporarily disable `--optimize` to see if the issue is related to aggressive optimizations.

Warnings

breaking As a relatively new project (v1.0.2), UltraBundle's configuration schema (`bundles.json`) or CLI options might undergo breaking changes in future major versions. Users should review release notes carefully when upgrading to new major versions.
Fix: Always check the official documentation or release notes for schema updates when upgrading to a new major version. Consider pinning to a specific major version to avoid unexpected build failures.
gotcha UltraBundle's 'aggressive' optimizations, powered by Rollup, may unexpectedly remove code or side effects that are crucial for certain libraries or frameworks. This is common with strict tree-shaking.
Fix: If encountering unexpected runtime errors or missing functionality, examine the bundled output. Look for `sideEffects: false` in `package.json` of affected libraries or use `/* #__PURE__ */` annotations for functions with side effects. Consult Rollup documentation for advanced `treeshake` options if UltraBundle exposes them or if a custom Rollup config can be injected.
gotcha UltraBundle relies on a `bundles.json` file in the project root. If this file is missing, malformed, or located elsewhere, the bundling process will fail or produce an empty output.
Fix: Ensure `bundles.json` exists in the same directory as `package.json` and follows the specified JSON array format. Verify all `input` and `output` paths are correct and accessible.
gotcha While UltraBundle ships with TypeScript support, misconfigured `tsconfig.json` or incompatible TypeScript versions can lead to compilation errors during bundling.
Fix: Ensure your project's `tsconfig.json` is correctly set up for your project, especially `target` and `module` options. Update TypeScript to a compatible version with UltraBundle and Rollup's underlying TS transformer. Check UltraBundle's GitHub issues for reported TS compatibility problems.

Install

npm install ultrabundle npm
yarn add ultrabundle yarn
pnpm add ultrabundle pnpm

Imports

ultrabundle CLI (Development)
wrong:
```
import { ultrabundle } from 'ultrabundle'
```
correct:
```
"dev": "ultrabundle"
```
UltraBundle is a CLI tool and not imported into JavaScript/TypeScript files. Its primary usage is via `package.json` scripts.
ultrabundle CLI (Watch Mode)
wrong:
```
require('ultrabundle').watch()
```
correct:
```
"watch": "ultrabundle --watch"
```
Commands are executed directly as npm scripts or via `npx` for watch mode, which enables file watching.
ultrabundle CLI (Production Optimize)
wrong:
```
ultrabundle.optimize({ ... })
```
correct:
```
"prod": "ultrabundle --optimize"
```
For production builds, the `--optimize` flag triggers additional optimizations. The configuration is handled through `bundles.json`, not programmatic API.

Quickstart

Demonstrates the typical setup for UltraBundle, including `package.json` scripts and the required `bundles.json` configuration file, showing a basic TypeScript input and JavaScript output.

{
  "name": "my-app",
  "version": "1.0.0",
  "description": "My UltraBundled application",
  "main": "dist/output.js",
  "scripts": {
    "dev": "ultrabundle",
    "watch": "ultrabundle --watch",
    "prod": "ultrabundle --optimize"
  },
  "devDependencies": {
    "ultrabundle": "^1.0.0"
  }
}
// -- In bundles.json --
[
  {
    "input": "src/index.ts",
    "output": "dist/output.js"
  }
]
// -- In src/index.ts --
console.log("Hello from UltraBundle!");

// To run:
// 1. npm install
// 2. npm run dev (for development build)
// 3. npm run watch (for continuous watching and rebuilding)
// 4. npm run prod (for optimized production build)

view raw JSON →