ts-invariant: TypeScript Assertions

Common errors

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

  cause This error occurs when `process` is accessed in a browser environment, and it has not been properly polyfilled or defined by the bundler.
  fix Configure your bundler to provide a `process.env` polyfill or replacement. For Webpack, use `new webpack.DefinePlugin({ 'process.env.NODE_ENV': JSON.stringify(process.env.NODE_ENV) });`. For Rollup, use `@rollup/plugin-replace`.

• Invariant Violation: Username must be defined and not empty.

  cause This is the expected runtime error when an `invariant` condition evaluates to false. If this occurs in a production environment where messages are typically stripped, it implies that the stripping mechanism is not active or correctly configured.
  fix During development, this is a signal to fix the underlying condition. In production, if messages are not stripped, verify your bundler's configuration for `process.env.NODE_ENV` and the invariant stripping plugin.

• TypeError: (0, ts_invariant__WEBPACK_IMPORTED_MODULE_0__.invariant) is not a function

  cause This usually indicates an incorrect import statement, where `invariant` is attempted to be imported as a default export rather than a named export, especially in CommonJS contexts or misconfigured ESM.
  fix Change your import statement from `import invariant from 'ts-invariant';` to `import { invariant } from 'ts-invariant';`. If using CommonJS, ensure transpilation or use `const { invariant } = require('ts-invariant');` (though ESM is preferred).

Warnings

• gotcha Error messages from `invariant` and its logging methods (`invariant.log`, `invariant.warn`, `invariant.error`) can be stripped from production bundles. This is typically done by bundler plugins (e.g., `rollup-plugin-invariant`, though now archived). While beneficial for bundle size, it means production builds might not show detailed assertion messages, making debugging production issues challenging if unaware.
  Fix: Ensure `process.env.NODE_ENV` is correctly set to 'development' during development builds to retain messages. For production debugging, either temporarily disable stripping or rely on stack traces and code context.
• gotcha `ts-invariant` often relies on `process.env.NODE_ENV` to determine its behavior, especially regarding message stripping. If `process.env` is not properly polyfilled or replaced by a bundler in non-Node.js environments (like browsers), it might lead to unexpected runtime behavior or errors.
  Fix: When bundling for browsers, ensure your bundler (e.g., Webpack, Rollup, Vite) correctly defines or polyfills `process.env.NODE_ENV`. For Webpack, use `DefinePlugin`; for Rollup, use `@rollup/plugin-replace`.
• breaking The `rollup-plugin-invariant` package, which was commonly used to strip `ts-invariant` messages in production, has been moved to an archived directory by the Apollo GraphQL team. While its functionality might still work, it indicates a lack of active maintenance and potential for future compatibility issues with newer Rollup versions or other tooling.
  Fix: Consider migrating to alternative bundler plugins or custom configurations that achieve similar dead-code elimination if you rely on stripping invariant messages. Verify continued compatibility if you remain on `rollup-plugin-invariant`.

Install

• npm install ts-invariant npm
• yarn add ts-invariant yarn
• pnpm add ts-invariant pnpm

Imports

• invariant
  wrong:

  import invariant from 'ts-invariant';

  correct:

  import { invariant } from 'ts-invariant';

  The core `invariant` function is a named export, not a default export.
• setVerbosity
  wrong:

  const { setVerbosity } = require('ts-invariant');

  correct:

  import { setVerbosity } from 'ts-invariant';

  CommonJS `require` for ESM-first packages can lead to module resolution issues, especially in newer Node.js environments or with strict bundler configurations.
• InvariantError

  import { InvariantError } from 'ts-invariant';

  Used for `instanceof` checks when catching errors thrown by `invariant`.

Quickstart

Demonstrates importing `invariant`, `setVerbosity`, and `InvariantError`, showing basic assertion, logging levels, and the effect of verbosity settings. It also highlights `process.env.NODE_ENV` behavior.

import { invariant, setVerbosity, InvariantError } from "ts-invariant";

// Default verbosity is 'log'
console.log("--- Default verbosity (log) ---");

// This will throw an InvariantError if the condition is false
try {
  const username: string | undefined = undefined;
  invariant(username, "Username must be defined and not empty.");
} catch (e) {
  if (e instanceof InvariantError) {
    console.error("Invariant failed as expected:", e.message);
  } else {
    console.error("Unexpected error:", e);
  }
}

// Log a warning message
invariant.warn("This is a warning message that will be displayed by default.");

// Change verbosity to suppress log messages
console.log("\n--- Setting verbosity to 'warn' ---");
setVerbosity("warn");

// This log will now be suppressed and not appear in the console
invariant.log("This log message should be suppressed at 'warn' verbosity.");

// This warning will still show
invariant.warn("This warning message should still show at 'warn' verbosity.");

// This error will still show
invariant.error("This error message should still show at 'warn' verbosity.");

// Revert verbosity to default for further operations or tests
setVerbosity("log");
console.log("\n--- Verbosity reverted to 'log' ---");

// Example of how invariants are often handled for production builds
// In production, bundlers might strip these messages for smaller bundles.
if (process.env.NODE_ENV === 'production') {
  // In a real production build, this invariant message might be stripped.
  invariant(false, "This message is for dev only. Production build will strip it if configured.");
} else {
  invariant.log("In development, invariant messages (like the one above) are usually active for debugging.");
}