{"id":16832,"library":"if-tsb","title":"Insanely Fast TypeScript Bundler","description":"The `if-tsb` package, currently at version 1.1.2, is a TypeScript-focused bundler emphasizing speed and extensive configuration via `tsconfig.json`. It aims to provide a fast solution for compiling and bundling TypeScript projects, producing deployable JavaScript output. While a specific release cadence isn't published, its 1.x.x versioning suggests active development. Key differentiators include its deep integration with `tsconfig.json` for defining single or multiple entry points, custom output paths using template variables (e.g., `[name].bundled.js`), and a broad set of `bundlerOptions`. These options offer fine-grained control over aspects like module format (including non-standard ones like 'none', 'private'), external bundling, source map generation, and pre-import optimizations. It provides both a command-line interface for common bundling tasks and a programmatic API for integration into custom build workflows, distinguishing itself from general-purpose bundlers that typically rely on separate configuration files or a more standard set of module transformation options.","status":"active","version":"1.1.2","language":"javascript","source_language":"en","source_url":"https://github.com/bdsx/if-tsb","tags":["javascript","typescript","bundler","bundling"],"install":[{"cmd":"npm install if-tsb","lang":"bash","label":"npm"},{"cmd":"yarn add if-tsb","lang":"bash","label":"yarn"},{"cmd":"pnpm add if-tsb","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"const { bundle } = require('if-tsb');","symbol":"bundle","correct":"import { bundle } from 'if-tsb';"},{"note":"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.","wrong":"const { bundleWatch } = require('if-tsb');","symbol":"bundleWatch","correct":"import { bundleWatch } from 'if-tsb';"}],"quickstart":{"code":"/*\n// 1. Install if-tsb globally\nnpm install -g if-tsb\n\n// 2. Create your TypeScript source file (e.g., src/index.ts):\n*/\n\n// src/index.ts\nconsole.log(\"Hello from if-tsb!\");\nexport function calculateSum(a: number, b: number): number {\n  return a + b;\n}\n\n/*\n// 3. Create or update your tsconfig.json in the project root:\n//    This configures both TypeScript compilation and if-tsb bundling.\n*/\n\n// tsconfig.json\n{\n  \"compilerOptions\": {\n    \"target\": \"es2020\",\n    \"module\": \"commonjs\",\n    \"outDir\": \"./dist\",\n    \"strict\": true,\n    \"esModuleInterop\": true,\n    \"forceConsistentCasingInFileNames\": true\n  },\n  // if-tsb specific configuration for entry and output\n  \"entry\": \"./src/index.ts\",\n  \"output\": \"./dist/bundle.js\",\n  \"bundlerOptions\": {\n    \"cleanConsole\": true, // Clear console before each rebuild in watch mode\n    \"verbose\": true       // Enable verbose output during bundling\n  }\n}\n\n/*\n// 4. Run if-tsb from your project root (where tsconfig.json is):\n//    if-tsb will read the 'entry' and 'output' from tsconfig.json\n*/\n\n// Execute in your terminal:\n// if-tsb ./tsconfig.json\n\n/*\n// Expected output structure after running:\n// ./dist/bundle.js (the bundled JavaScript)\n// ./dist/bundle.d.ts (the bundled declaration file if declarations are enabled)\n\n// You can then use the bundled file:\n// const { calculateSum } = require('./dist/bundle');\n// console.log('Sum:', calculateSum(5, 7)); // Output: Sum: 12\n*/","lang":"typescript","description":"Demonstrates how to install `if-tsb` and use its command-line interface to bundle a TypeScript project using configuration defined directly within `tsconfig.json`."},"warnings":[{"fix":"Prefer `import { bundle, bundleWatch } from 'if-tsb';` for programmatic API usage in TypeScript or ESM projects.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"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.","cause":"The `if-tsb` package is not installed or not accessible in the current execution environment.","error":"Error: Cannot find module 'if-tsb'"},{"fix":"Ensure you are using `import { bundle } from 'if-tsb';` and that your project is configured for ES Modules if using programmatic API.","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.","error":"TypeError: bundle is not a function"},{"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.","cause":"The 'entry' path specified in `tsconfig.json` or as a CLI argument does not correctly point to an existing TypeScript file.","error":"TS2307: Cannot find module './entry.ts' or its corresponding type declarations."},{"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).","cause":"The `entry` field within `tsconfig.json` is malformed or uses an unsupported type/structure for `if-tsb`'s configuration.","error":"Error: Invalid 'entry' configuration in tsconfig.json. Expected string, array, or object."}],"ecosystem":"npm","meta_description":null}