UT Tools for Build and Release Automation

Common errors

• Error: Command 'ut-lint' not found

  cause The `ut-tools` package was not installed globally, or the global `node_modules` bin directory is not in your system's PATH.
  fix Ensure `ut-tools` is installed globally by running `npm install -g ut-tools`. Verify your system's PATH includes the global npm bin directory.

• ESLint: Cannot read config file: '/enter the installation path here/ut-tools/eslint/.eslintrc.js'

  cause The `eslint.options.overrideConfigFile` setting in VSCode uses an incorrect or unresolvable path to the `ut-tools` ESLint configuration.
  fix Find the correct global installation path of `ut-tools` (e.g., `npm root -g`) and update your VSCode settings with the precise path to the `.eslintrc.js` file.

• npm install takes a long time, even for small projects.

  cause Prior to v7, `ut-tools` was often listed as a `devDependency`. Since v7, it is designed for global installation, and local installation adds unnecessary overhead.
  fix Remove `ut-tools` from your `devDependencies` in `package.json` and ensure it is installed globally (`npm install -g ut-tools`).

Warnings

• breaking Since version 7, ut-tools must be installed globally (`npm install -g ut-tools`) rather than as a `devDependencies` entry. Installing it locally will not provide the expected CLI commands and may slow down `npm install` processes.
  Fix: Remove `ut-tools` from your `package.json` `devDependencies` and install it globally using `npm install -g ut-tools`.
• gotcha Configuring VSCode ESLint to use ut-tools's predefined rules requires specific workspace or user settings. Incorrect paths will result in VSCode not applying the linting rules or reporting errors.
  Fix: Add the following to your VSCode settings (user or workspace): `"eslint.options": { "overrideConfigFile": "/path/to/global/npm/node_modules/ut-tools/eslint/.eslintrc.js" }, "eslint.nodePath": "/path/to/global/npm/node_modules/ut-tools/node_modules"`. Replace `/path/to/global/npm/node_modules` with your actual global npm modules path (e.g., `npm root -g`).
• gotcha ut-tools is designed as a collection of command-line utilities and is not intended for programmatic `import` or `require()` within JavaScript or TypeScript application code. Attempting to import symbols directly will fail.
  Fix: Use the provided scripts as CLI commands in your `package.json` or directly from the terminal. For example, `npm run lint` or `ut-lint`.

Install

• npm install ut-tools npm
• yarn add ut-tools yarn
• pnpm add ut-tools pnpm

Imports

• ut-changelog
  wrong:

  import { changelog } from 'ut-tools'

  correct:

  ut-changelog

  This package primarily exposes CLI commands, not library functions for programmatic import. Use directly in package.json scripts or via npx.
• ut-lint
  wrong:

  const lint = require('ut-tools/lint');

  correct:

  ut-lint

  Invoke ut-lint as a shell command. It's not a JavaScript module to be imported.
• ut-release
  wrong:

  import { release } from 'ut-tools';

  correct:

  ut-release

  Execute ut-release as a command-line utility for managing package versions and publishing.

Quickstart

Demonstrates global installation and usage of ut-tools commands within package.json scripts.

npm install -g ut-tools

// Add to your project's package.json scripts
// Example: package.json
/*
{
  "name": "my-project",
  "version": "1.0.0",
  "scripts": {
    "lint": "ut-lint",
    "test": "ut-test",
    "release": "ut-release"
  }
}
*/

// Then run from your project directory
npm run lint