Insanely Fast TypeScript Bundler

Common errors

• Error: Cannot find module 'if-tsb'

  cause The `if-tsb` package is not installed or not accessible in the current execution environment.
  fix Install the package globally with `npm install -g if-tsb` for CLI usage, or locally with `npm install --save-dev if-tsb` for programmatic usage.

• TypeError: bundle is not a function

  cause Attempting to use the `bundle` function with incorrect import syntax (e.g., `const bundle = require('if-tsb');` or a wrong named import) in an environment expecting ES Modules.
  fix Ensure you are using `import { bundle } from 'if-tsb';` and that your project is configured for ES Modules if using programmatic API.

• TS2307: Cannot find module './entry.ts' or its corresponding type declarations.

  cause The 'entry' path specified in `tsconfig.json` or as a CLI argument does not correctly point to an existing TypeScript file.
  fix Verify that the path provided in the `entry` field of `tsconfig.json` or as a command-line argument (`if-tsb ./path/to/entry.ts`) is correct and the file exists relative to the execution context.

• Error: Invalid 'entry' configuration in tsconfig.json. Expected string, array, or object.

  cause The `entry` field within `tsconfig.json` is malformed or uses an unsupported type/structure for `if-tsb`'s configuration.
  fix Refer to the `if-tsb` documentation for the correct `tsconfig.json` `entry` formats (e.g., string for single entry, array for multiple, object for specific outputs).

Warnings

• gotcha The README's API usage example shows a CommonJS `require()` statement. While this might work in certain Node.js environments or with specific bundler configurations, modern TypeScript projects typically use ESM `import` statements. Relying on `require()` might lead to issues in pure ESM environments or when using other tooling.
  Fix: Prefer `import { bundle, bundleWatch } from 'if-tsb';` for programmatic API usage in TypeScript or ESM projects.
• gotcha Many of `if-tsb`'s core bundling configurations, such as `entry`, `output`, and the entire `bundlerOptions` object, are custom properties added directly to `tsconfig.json`. These are not standard TypeScript compiler options and will be ignored by other TypeScript tooling or bundlers like `tsc`, Webpack, or Rollup. This can lead to confusion if users expect universal `tsconfig.json` behavior.
  Fix: Be aware that `if-tsb` extends `tsconfig.json` with its own specific configuration fields. These fields are parsed only by `if-tsb` itself. When integrating with other tools, separate configurations might be necessary.
• gotcha The `bundlerOptions.module` setting provides several non-standard values (e.g., "none", "private", "self", "window", "this", "var (varname)", "let (varname)", "const (varname)"). These are specific to `if-tsb`'s internal module handling and do not directly correspond to standard JavaScript module formats like CommonJS or ES Modules. Using these options might result in highly customized and potentially less interoperable bundled output.
  Fix: Carefully review the documentation for each `bundlerOptions.module` value to understand its specific output format and implications for your project's runtime environment and module loading strategy. For standard module outputs, use 'commonjs' if supported or rely on the default if it aligns with standard ES module output.

Install

• npm install if-tsb npm
• yarn add if-tsb yarn
• pnpm add if-tsb pnpm

Imports

• bundle
  wrong:

  const { bundle } = require('if-tsb');

  correct:

  import { bundle } from 'if-tsb';

  While the README's API example uses CommonJS `require()`, `if-tsb` ships with TypeScript types and is intended for use in modern TypeScript projects, where ESM `import` is the standard.
• bundleWatch
  wrong:

  const { bundleWatch } = require('if-tsb');

  correct:

  import { bundleWatch } from 'if-tsb';

  This function is used for initiating a watch mode, allowing automatic re-bundling of TypeScript files upon changes, which is beneficial for development workflows. Similar to `bundle`, ESM `import` is preferred.

Quickstart

Demonstrates how to install `if-tsb` and use its command-line interface to bundle a TypeScript project using configuration defined directly within `tsconfig.json`.

/*
// 1. Install if-tsb globally
npm install -g if-tsb

// 2. Create your TypeScript source file (e.g., src/index.ts):
*/

// src/index.ts
console.log("Hello from if-tsb!");
export function calculateSum(a: number, b: number): number {
  return a + b;
}

/*
// 3. Create or update your tsconfig.json in the project root:
//    This configures both TypeScript compilation and if-tsb bundling.
*/

// tsconfig.json
{
  "compilerOptions": {
    "target": "es2020",
    "module": "commonjs",
    "outDir": "./dist",
    "strict": true,
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true
  },
  // if-tsb specific configuration for entry and output
  "entry": "./src/index.ts",
  "output": "./dist/bundle.js",
  "bundlerOptions": {
    "cleanConsole": true, // Clear console before each rebuild in watch mode
    "verbose": true       // Enable verbose output during bundling
  }
}

/*
// 4. Run if-tsb from your project root (where tsconfig.json is):
//    if-tsb will read the 'entry' and 'output' from tsconfig.json
*/

// Execute in your terminal:
// if-tsb ./tsconfig.json

/*
// Expected output structure after running:
// ./dist/bundle.js (the bundled JavaScript)
// ./dist/bundle.d.ts (the bundled declaration file if declarations are enabled)

// You can then use the bundled file:
// const { calculateSum } = require('./dist/bundle');
// console.log('Sum:', calculateSum(5, 7)); // Output: Sum: 12
*/