Build Utilities Collection

Common errors

• ReferenceError: require is not defined in ES module scope

  cause Attempting to use `require()` in an ECMAScript Module (ESM) context when `build-utils` is a CommonJS-only package.
  fix Change your file's extension to `.cjs` or ensure your `package.json` specifies `"type": "commonjs"`. Alternatively, use dynamic `import()` for CJS modules within ESM, but be aware of potential interoperability complexities.

• TypeError: Cannot read properties of undefined (reading 'createDirectory')

  cause This error typically occurs when trying to destructure a property from `undefined`. It implies that `require('build-utils')` did not return an object with a `fs` property, or `fs` did not have `createDirectory`, likely due to incorrect import path or module resolution issues.
  fix Ensure you are correctly accessing utilities under their respective namespaces (e.g., `require('build-utils').fs.createDirectory`). Verify the exact function name and nesting from the package's source or documentation.

• Error: spawn ENOENT

  cause The `exec` or `spawn` utility within `build-utils.process` could not find the specified command in the system's PATH. This is a common operating system error when trying to run an unrecognized executable.
  fix Check that the command you are trying to execute (`ls`, `git`, `npm`, etc.) is installed and accessible in the system's PATH environment variable. Provide the full path to the executable if it's not globally available.

Warnings

• breaking The `build-utils` package was last published in August 2018. It is unmaintained, which means there will be no new features, bug fixes, or security updates. Users should consider migrating to actively maintained alternatives for critical projects.
  Fix: Evaluate actively maintained build utility libraries or implement functionalities using Node.js's native `fs`, `child_process`, and `path` modules.
• breaking This package is exclusively designed for CommonJS (CJS) environments and does not support ECMAScript Modules (ESM) syntax. Attempting to use `import` statements will lead to runtime errors in Node.js ESM projects.
  Fix: Ensure your project is configured for CommonJS, or use `require()` statements within a CJS-compatible file. For ESM projects, consider modern dual-module libraries.
• gotcha Compatibility with newer Node.js versions is uncertain due to the package's age. It may rely on deprecated Node.js APIs or exhibit unexpected behavior with recent runtime changes, potentially leading to instability or subtle bugs.
  Fix: Test thoroughly on your target Node.js version. If issues arise, direct replacement with Node.js built-ins or newer libraries is recommended.
• gotcha The globbing utilities (`copyGlob`, `deleteGlob`, `searchGlob`) might use an outdated or custom glob implementation. This could lead to different behavior compared to modern, widely adopted globbing libraries (e.g., `fast-glob`), affecting pattern matching and file resolution.
  Fix: Verify glob patterns rigorously, especially for complex scenarios. If discrepancies are found, consider using a dedicated and maintained globbing library in conjunction with this package or as a replacement.

Install

• npm install build-utils npm
• yarn add build-utils yarn
• pnpm add build-utils pnpm

Imports

• createDirectory
  wrong:

  import { createDirectory } from 'build-utils';

  correct:

  const { createDirectory } = require('build-utils');

  This package is CommonJS-only due to its last publish date in 2018. ESM import syntax will result in a runtime error.
• spawn
  wrong:

  import { process } from 'build-utils'; const { spawn } = process;

  correct:

  const { spawn } = require('build-utils').process;

  Functions are often grouped under namespaces like `process`. Direct ESM imports are not supported.
• deepAssign
  wrong:

  import deepAssign from 'build-utils/object';

  correct:

  const { deepAssign } = require('build-utils').object;

  Individual utilities are exposed via their category namespace (e.g., `object.deepAssign`). Referencing sub-paths or default imports will not work.

Quickstart

This quickstart demonstrates basic file system operations (create, write, delete) and process execution using `build-utils` in a CommonJS Node.js environment.

const { createDirectory, writeFile, deleteDirectory } = require('build-utils').fs;
const { exec } = require('build-utils').process;
const path = require('path');

async function runBuildProcess() {
  const tempDir = path.join(__dirname, 'temp-output');
  const tempFile = path.join(tempDir, 'artifact.txt');

  console.log(`Creating directory: ${tempDir}`);
  await createDirectory(tempDir);
  console.log('Directory created.');

  console.log(`Writing file: ${tempFile}`);
  await writeFile(tempFile, 'This is a build artifact generated by build-utils.\nHello, World!');
  console.log('File written.');

  console.log('Executing a command: ls');
  try {
    const { stdout, stderr } = await exec('ls -l ' + tempDir);
    console.log('Stdout:', stdout);
    if (stderr) console.error('Stderr:', stderr);
  } catch (error) {
    console.error('Error executing command:', error.message);
  }

  console.log(`Cleaning up directory: ${tempDir}`);
  await deleteDirectory(tempDir);
  console.log('Cleanup complete.');
}

runBuildProcess().catch(console.error);