Registry / devops / build-if-changed

build-if-changed

JSON →
library1.5.5jsnpmunverified

build-if-changed (bic) is a utility designed to optimize monorepo build processes by executing `npm run build` scripts only for packages that have undergone changes since their last build. It achieves this by crawling specified directories within a package, generating SHA-1 hashes of watched files, and storing them in a `.bic_cache` file alongside each `package.json`. If the hashes indicate a change, the build script is triggered. The current stable version is 1.5.5. It focuses on reducing build times and CI/CD costs by avoiding redundant builds, differentiating itself through its simple `package.json`-based configuration and custom glob syntax for file watching.

npm install build-if-changed
INSTALL
IMPORT
SIG · BUILD-IF-CHANGED
B
build-if-changed
devopsjavascriptv1.5.5
harness data pending
Install & Compatibility
Where this runs

No compatibility data collected yet for this library.

Code
Verified usage

This quickstart installs `build-if-changed`, creates a dummy `package.json` with a build script, runs `bic` initially, then simulates a file change to demonstrate how `bic` triggers a build only when necessary.

const { execSync } = require('child_process'); const fs = require('fs'); const path = require('path'); // Ensure a package.json exists for a mock build const pkgPath = path.join(process.cwd(), 'package.json'); if (!fs.existsSync(pkgPath)) { console.log('Creating a dummy package.json...'); fs.writeFileSync(pkgPath, JSON.stringify({ "name": "my-test-app", "version": "1.0.0", "scripts": { "build": "echo 'Building my-test-app...' && touch build-output.txt" }, "devDependencies": {} }, null, 2)); } console.log('Installing build-if-changed as a dev dependency...'); execSync('npm install build-if-changed -D', { stdio: 'inherit' }); console.log('Running build-if-changed for the first time...'); execSync('npx build-if-changed', { stdio: 'inherit' }); // Simulate a file change to trigger a build next time console.log('\nSimulating a file change...'); fs.writeFileSync(path.join(process.cwd(), 'src/index.js'), '// Some new content', { flag: 'a' }); console.log('Running build-if-changed again after a change...'); execSync('npx build-if-changed', { stdio: 'inherit' }); console.log('\nCleanup (optional)...'); // fs.unlinkSync(pkgPath); // fs.unlinkSync(path.join(process.cwd(), '.bic_cache')); // fs.rmSync(path.join(process.cwd(), 'node_modules'), { recursive: true, force: true }); // fs.rmSync(path.join(process.cwd(), 'src'), { recursive: true, force: true }); console.log('Quickstart complete. Check build-output.txt.');
bic --version
Debug
Known issues
gotchaThe `bic` configuration in `package.json` uses a custom glob syntax, not standard glob patterns. Refer to the `recrawl` package documentation for specific pattern syntax rules.
fix
Consult the `recrawl` package documentation (e.g., `https://www.npmjs.com/package/recrawl#pattern-syntax`) to correctly define file watch patterns in your `package.json` `bic` field.
affects: >=1.0.0
gotchaWhen configuring watched files via the `bic` field in `package.json`, the `skip` array takes precedence over the `only` array. Files explicitly listed in `skip` will always be ignored, even if also present in `only`.
fix
Structure your `bic` configuration with `skip` patterns as overriding exclusions. Ensure files you intend to watch are not inadvertently included in `skip`.
affects: >=1.0.0
gotchaBy default, the `.git` and `node_modules` directories are always skipped during file crawling. This behavior cannot be overridden by `only` configurations.
fix
Plan your file watching configurations knowing that version control and dependency directories are inherently ignored by `build-if-changed`.
affects: >=1.0.0
gotchaAny package whose 'build' script in `package.json` contains either 'bic' or 'build-if-changed' will be skipped to prevent infinite loops.
fix
Ensure your `build` script does not contain 'bic' or 'build-if-changed' as substrings if you intend for `build-if-changed` to run it. For example, use `my:build` instead of `bic:build`.
affects: >=1.0.0
Errors
Common errors & fixes
Error: Command failed with exit code 127: build-if-changed
The `build-if-changed` command (or `bic` alias) is not found in the system's PATH, usually because the package was not installed or installed incorrectly.
fix
Install `build-if-changed` as a dev dependency (`npm install build-if-changed -D` or `yarn add build-if-changed -D`) and then run it using `npx build-if-changed` (for npm) or `yarn build-if-changed` (for yarn).
No build scripts found in the following packages: [list of packages]
The specified packages' `package.json` files do not contain a `scripts.build` entry, which `build-if-changed` expects to execute.
fix
Add a `"build": "your-build-command-here"` entry to the `scripts` section of the `package.json` for each package that `build-if-changed` should process.
Files are not being watched/skipped as expected.
Incorrect `bic` configuration in `package.json`, often due to misunderstanding the custom glob syntax or `skip`/`only` precedence.
fix
Carefully review the `bic` field in your `package.json`. Verify the custom glob patterns against the `recrawl` documentation and ensure the `skip` array does not inadvertently exclude desired files.
Upgrade
Version history
1.5.5latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
10 hits · last 30 days
node
10
Resources
build-if-changed — npm install build-if-changed · libregistry