{"id":12197,"library":"tslib","title":"TypeScript Runtime Helper Library","description":"tslib is a compact runtime library provided by Microsoft that contains all the essential helper functions emitted by the TypeScript compiler. It is primarily used in conjunction with the `--importHelpers` compiler option, which instructs TypeScript to import these common helper functions (such as `__extends`, `__assign`, `__decorate`, `__awaiter`) from `tslib` rather than embedding them directly in every compiled output file. This approach leads to significantly smaller JavaScript bundles and reduced runtime overhead by avoiding redundant function declarations. The current stable version is 2.8.1, with frequent patch and minor releases aligning with TypeScript's development. It differentiates itself by being the official, highly optimized runtime solution for TypeScript's emitted code, ensuring maximum compatibility and efficiency for projects compiled with TypeScript.","status":"active","version":"2.8.1","language":"javascript","source_language":"en","source_url":"https://github.com/Microsoft/tslib","tags":["javascript","TypeScript","Microsoft","compiler","language","tslib","runtime","typescript"],"install":[{"cmd":"npm install tslib","lang":"bash","label":"npm"},{"cmd":"yarn add tslib","lang":"bash","label":"yarn"},{"cmd":"pnpm add tslib","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"const { __assign } = require('tslib');","symbol":"__assign","correct":"import { __assign } from 'tslib';"},{"note":"There is no default export for individual helpers. Always use named imports for specific tslib functions. This helper is crucial for downleveling `async/await`.","wrong":"import __awaiter from 'tslib';","symbol":"__awaiter","correct":"import { __awaiter } from 'tslib';"},{"note":"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.","wrong":"const decorate = require('tslib').__decorate;","symbol":"__decorate","correct":"import { __decorate } from 'tslib';"},{"note":"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.","wrong":"import * as tslib from 'tslib'; const myModule = tslib.__importStar(someObject);","symbol":"__importStar","correct":"import { __importStar } from 'tslib';"}],"quickstart":{"code":"{\n  \"compilerOptions\": {\n    \"importHelpers\": true,\n    \"target\": \"es2016\",\n    \"module\": \"commonjs\",\n    \"strict\": true,\n    \"esModuleInterop\": true,\n    \"skipLibCheck\": true,\n    \"forceConsistentCasingInFileNames\": true\n  }\n}","lang":"json","description":"Configures TypeScript to automatically import helper functions from `tslib`, reducing code duplication and bundle size. Requires `npm install tslib`."},"warnings":[{"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+.","message":"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.","severity":"breaking","affected_versions":"<2.0"},{"fix":"Upgrade to `tslib@^2.5.1` or later to ensure proper module resolution with modern TypeScript compiler settings and bundlers.","message":"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.","severity":"gotcha","affected_versions":"<2.5.1"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<2.6.0"},{"fix":"Upgrade to `tslib@^2.8.1` to ensure `__importStar` accurately reflects the properties of imported modules, including non-enumerable ones.","message":"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.","severity":"gotcha","affected_versions":"<2.8.1"},{"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.","message":"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.","severity":"deprecated","affected_versions":">=2.5.3"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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`).","cause":"The `tslib` package is missing, or module resolution is failing to locate it when `importHelpers` is enabled in `tsconfig.json`.","error":"Error: Cannot find module 'tslib' or its corresponding type declarations."},{"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.","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.","error":"TypeError: tslib_1.__assign is not a function"},{"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.","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.","error":"ReferenceError: __awaiter is not defined"}],"ecosystem":"npm"}