tinybundle

2.0.0 · active · verified Tue Apr 21

tinybundle is a minimalist command-line module bundler, currently at version 2.0.0, designed for simple bundling tasks without the complexity of modern bundlers like Webpack or Rollup. It distinguishes itself by eschewing a JavaScript API, relying solely on CLI arguments and a `tbdeps.json` configuration file. This file specifies a list of npm packages and local JavaScript files (prefixed with `!`), optionally allowing for pre-processing commands (prefixed with `?`) to be executed via `system` calls before bundling. The tool does not support traditional loaders, opting instead for this external command execution model. Its release cadence is not specified, but it targets users looking for an extremely lightweight, no-frills bundling solution where custom pre-processing can be scripted externally. It consolidates dependencies and local code into a single, minified output file.

Common errors

```
Error: Cannot find module 'some-package'
```
cause An npm package listed in `tbdeps.json` was not found in the `node_modules` directory.

fix Ensure all required npm packages are installed via `npm install <package-name>` in your project.
```
command not found: tinybundle
```
cause The `tinybundle` executable is not in your system's PATH or not globally installed.

fix Install tinybundle globally using `npm install -g tinybundle` or run it via `npx tinybundle`.
```
SyntaxError: Unexpected token '<' (for JSX) or 'SyntaxError: Cannot use import statement outside a module' (for ESM in CJS context)
```
cause tinybundle does not inherently understand non-standard JavaScript syntax (like JSX) or different module systems (ESM vs. CJS) without pre-processing.

fix Add a pre-processing step using the `?` prefix in `tbdeps.json` to transpile your code (e.g., `?npx buble input.jsx -o output.js`) before including the output with `!`.

Warnings

gotcha tinybundle is exclusively a CLI tool and offers no programmatic JavaScript API. It cannot be imported or used directly within Node.js applications.
Fix: Interact with tinybundle only via the command line or through shell scripts.
gotcha The bundler does not support built-in loaders for languages like TypeScript, JSX, or CSS. All non-standard JavaScript must be pre-processed using external commands.
Fix: Utilize the `?` prefix in `tbdeps.json` to execute external commands (e.g., Babel, Buble, TypeScript compiler) to transform files before bundling. Ensure the output of these commands is then included with `!`.
gotcha Commands prefixed with `?` in `tbdeps.json` are executed as `system()` calls, which can have security implications or unexpected behavior depending on the execution environment and the commands used.
Fix: Carefully vet any commands executed via the `?` prefix. Avoid running untrusted commands or scripts with elevated privileges.
gotcha tinybundle outputs a single, minified JavaScript file and does not support advanced bundling features like code splitting, tree shaking, or separate asset handling.
Fix: For projects requiring complex optimizations, code splitting, or handling of non-JavaScript assets (images, CSS), consider using more advanced bundlers like Webpack, Rollup, or esbuild.
gotcha All npm packages specified in `tbdeps.json` must be pre-installed in your project's `node_modules` directory before running tinybundle.
Fix: Run `npm install <package-name>` for all required npm packages before executing the `tinybundle` command.

Install

npm install tinybundle npm
yarn add tinybundle yarn
pnpm add tinybundle pnpm

Imports

tinybundle (default import)
wrong:
```
import tinybundle from 'tinybundle';
```
correct:
```
N/A - tinybundle is a CLI-only tool.
```
This package is designed exclusively for command-line usage and provides no JavaScript API or module exports for programmatic import.
tinybundle (named import)
wrong:
```
import { bundle } from 'tinybundle';
```
correct:
```
N/A - tinybundle is a CLI-only tool.
```
Attempts to import any symbols from 'tinybundle' will result in a module not found or undefined export error, as there are no exports.
tinybundle (CommonJS require)
wrong:
```
const tinybundle = require('tinybundle');
```
correct:
```
N/A - tinybundle is a CLI-only tool.
```
Use the `tinybundle` command directly from your terminal after global installation (`npm install -g tinybundle`) or via `npx tinybundle`.

Quickstart

Demonstrates bundling a third-party npm package (jQuery) and a local JavaScript file into a single output file using the tinybundle CLI and `tbdeps.json` configuration. The output bundle's content is then displayed.

mkdir my-bundle-project
cd my-bundle-project
npm init -y
npm install jquery
echo '["jquery", "!index.js"]' > tbdeps.json
echo 'console.log("Hello from index.js!");' > index.js
npx tinybundle ./dist/bundle.js
cat ./dist/bundle.js

view raw JSON →