TypeScript Runtime Helper Library

Common errors

• Error: Cannot find module 'tslib' or its corresponding type declarations.

  cause The `tslib` package is missing, or module resolution is failing to locate it when `importHelpers` is enabled in `tsconfig.json`.
  fix Run `npm install tslib` or `yarn add tslib`. Verify that `moduleResolution` in your `tsconfig.json` is correctly configured for your project (e.g., `node`, `node16`, `bundler`).

• TypeError: tslib_1.__assign is not a function

  cause TypeScript's emitted code expects `tslib` helpers to be available at runtime, but `tslib` either was not installed, was incorrectly installed, or a bundler failed to include or correctly process it in the final output.
  fix Ensure `tslib` is installed (`npm install tslib`) and that your build pipeline (e.g., webpack, Rollup, esbuild) is configured to include and correctly bundle `tslib`'s runtime helpers.

• ReferenceError: __awaiter is not defined

  cause This runtime error indicates that a `tslib` helper (such as `__awaiter` for `async/await`) is missing. This happens when `importHelpers` is enabled, but the `tslib` module is not loaded or its exports are inaccessible.
  fix Confirm `tslib` is a project dependency, is correctly installed, and that your module loader/bundler is successfully making the `tslib` helpers available at runtime. Ensure `tsconfig.json`'s `target` and `module` options are compatible with your runtime and `tslib` version.

Warnings

• breaking Older TypeScript versions require specific tslib versions. For TypeScript 3.8.4 or earlier, use `tslib@^1`. For TypeScript 2.3.2 or earlier, use `tslib@1.6.1`. Using a mismatch can lead to compilation errors or runtime issues where helpers are missing or incompatible.
  Fix: Check your `typescript` package version and install the compatible `tslib` version. For modern TypeScript (3.9.2+), `npm install tslib` typically installs the correct v2+.
• gotcha Projects using `moduleResolution: 'node16'` or `'bundler'` in `tsconfig.json` require `tslib@^2.5.1` or later due to changes in `package.json` exports field. Older versions might not resolve correctly, leading to 'Cannot find module' errors.
  Fix: Upgrade to `tslib@^2.5.1` or later to ensure proper module resolution with modern TypeScript compiler settings and bundlers.
• gotcha New language features like `using` and `await using` declarations (introduced in TypeScript 5.2+) require `tslib@^2.6.0` or later. Using an older `tslib` with these features will result in runtime errors due to missing helper functions.
  Fix: Upgrade `tslib` to version 2.6.0 or higher to correctly support the runtime helpers for `using` and `await using` syntax emitted by the TypeScript compiler.
• gotcha The `__importStar` helper, used for `import * as name from 'module'`, did not correctly include non-enumerable keys from the imported module prior to v2.8.1. This could lead to missing properties at runtime for certain modules.
  Fix: Upgrade to `tslib@^2.8.1` to ensure `__importStar` accurately reflects the properties of imported modules, including non-enumerable ones.
• deprecated The direct reference to `tslib.es6.js` from `package.json` exports was removed in `v2.5.3`. Projects relying on this specific path for ES6 output (e.g., custom bundler configurations) may experience broken imports.
  Fix: Rely on standard `package.json` `exports` or `module` fields for ES module resolution. Modern bundlers and TypeScript's `moduleResolution` settings should automatically resolve the correct entry point without direct path references.

Install

• npm install tslib npm
• yarn add tslib yarn
• pnpm add tslib pnpm

Imports

• __assign
  wrong:

  const { __assign } = require('tslib');

  correct:

  import { __assign } from 'tslib';

  While CommonJS destructuring is valid, the TypeScript compiler with `--importHelpers` typically emits `var tslib_1 = require("tslib"); exports.y = tslib_1.__assign({}, exports.x);`. Use named imports in ES Modules.
• __awaiter
  wrong:

  import __awaiter from 'tslib';

  correct:

  import { __awaiter } from 'tslib';

  There is no default export for individual helpers. Always use named imports for specific tslib functions. This helper is crucial for downleveling `async/await`.
• __decorate
  wrong:

  const decorate = require('tslib').__decorate;

  correct:

  import { __decorate } from 'tslib';

  Used when `emitDecoratorMetadata` is enabled. Ensure `tslib` is installed and resolved by your module system, especially in ES Module contexts where `require` is not available.
• __importStar
  wrong:

  import * as tslib from 'tslib'; const myModule = tslib.__importStar(someObject);

  correct:

  import { __importStar } from 'tslib';

  This pattern is not strictly 'wrong' but less direct. The `__importStar` helper itself is used by TypeScript to implement `import * as name from 'module'` semantics for older module targets. Fixed to include non-enumerable keys in v2.8.1.

Quickstart

Configures TypeScript to automatically import helper functions from `tslib`, reducing code duplication and bundle size. Requires `npm install tslib`.

{
  "compilerOptions": {
    "importHelpers": true,
    "target": "es2016",
    "module": "commonjs",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  }
}