{"id":12196,"library":"tshy","title":"tshy - TypeScript Hybridizer","description":"tshy (TypeScript Hybridizer) is a build tool designed to create hybrid npm packages that support both CommonJS (CJS) and ECMAScript Modules (ESM) simultaneously, primarily for Node.js environments. The current stable version is 4.1.1. It maintains an active development pace, with updates often aligning with new TypeScript releases. It differentiates itself by building the source code twice, once for ESM and once for CJS, using `tsc` (TypeScript compiler) versions 5.2+ (v4 defaults to TypeScript 6). It automatically manages the `exports` field in `package.json` to correctly point to the respective module entry points. Unlike some tools that attempt to mitigate the 'Dual Package Hazard,' tshy acknowledges it as an inherent aspect of Node.js module resolution and provides guidance on how package authors can handle potential duplicate module loading scenarios by leveraging global state rather than relying on strict singleton behavior within the module graph.","status":"active","version":"4.1.1","language":"javascript","source_language":"en","source_url":"https://github.com/isaacs/tshy","tags":["javascript","typescript","tsc","hybrid","esm","commonjs","build"],"install":[{"cmd":"npm install tshy","lang":"bash","label":"npm"},{"cmd":"yarn add tshy","lang":"bash","label":"yarn"},{"cmd":"pnpm add tshy","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"tshy utilizes `tsc` internally for TypeScript compilation. While tshy bundles a default TypeScript version (e.g., TS6 for v4+), users can explicitly specify their desired TypeScript version as a `devDependency` in their project's `package.json` to override tshy's default and ensure specific compiler behavior.","package":"typescript","optional":true}],"imports":[{"note":"tshy is primarily a command-line interface (CLI) tool. It is executed via npm scripts (e.g., `npm run prepare`) or directly as `tshy` from the terminal after local installation. It does not expose symbols or functions for direct `import` or `require` into your application's JavaScript/TypeScript source code.","wrong":"import tshy from 'tshy'; // tshy is not a library for direct import into application code","symbol":"(CLI tool)","correct":"n/a (tshy is executed as a command-line tool, typically via npm scripts)"}],"quickstart":{"code":"{\n  // package.json\n  \"name\": \"my-hybrid-package\",\n  \"version\": \"1.0.0\",\n  \"description\": \"A package built with tshy\",\n  \"main\": \"dist/commonjs/index.js\",\n  \"type\": \"commonjs\", // or module\n  \"files\": [\n    \"dist\"\n  ],\n  \"scripts\": {\n    \"build\": \"tshy\",\n    \"prepare\": \"npm run build\" // Runs tshy on npm install\n  },\n  \"devDependencies\": {\n    \"tshy\": \"^4.0.0\",\n    \"typescript\": \"^5.2.2\" // Optional: specify your TS version\n  },\n  \"exports\": {},\n  \"types\": \"dist/commonjs/index.d.ts\"\n}\n\n// src/index.ts\nexport const greet = (name: string): string => {\n  return `Hello, ${name}! This is a hybrid module built by tshy.`;\n};\n\nexport class Greeter {\n  private message: string;\n  constructor(name: string) {\n    this.message = `Greetings from ${name}.`;\n  }\n  sayHello(): string {\n    return this.message;\n  }\n}\n\n// To run this quickstart:\n// 1. Create a new directory and `npm init -y`\n// 2. Paste the package.json content above.\n// 3. Create a `src/index.ts` file with the content above.\n// 4. Run `npm install` (this will trigger the 'prepare' script).\n// 5. Observe 'dist/commonjs' and 'dist/esm' directories, and updated 'exports' in package.json.\n","lang":"typescript","description":"This quickstart demonstrates how to configure tshy in your `package.json` to build a hybrid TypeScript package, including a simple `src/index.ts` example. Running `npm install` will trigger tshy to compile your code into both CommonJS and ESM, updating the `package.json` exports accordingly."},"warnings":[{"fix":"If you encounter `tsc` errors after upgrading, try deleting your existing `tsconfig.json` file in your project root and then re-running `npm run build` (or `tshy`). This allows tshy to generate a new `tsconfig.json` file that is compatible with its default TypeScript version. Alternatively, explicitly install and specify your desired TypeScript version as a `devDependency` (e.g., `npm i -D typescript@5.4.5`).","message":"Upgrading tshy from v3 to v4 or v5 may cause TypeScript compilation errors. This is primarily due to tshy v4+ defaulting to TypeScript 6, which introduces new requirements for `tsconfig.json` and potential syntax changes that conflict with older configurations.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"When using tshy, avoid relying on strict singleton patterns or `instanceof` checks across potential CJS/ESM boundaries within the consuming application. If a true singleton is absolutely necessary, implement a robust global state management solution using `globalThis` and `Symbol.for` to ensure a single instance regardless of how the module is loaded, as demonstrated in tshy's documentation.","message":"tshy produces separate CommonJS and ESM builds that, from Node.js's perspective, are distinct modules. This means that if a consumer loads your package via `require()` in one part of their application and `import` in another, they will receive two separate instances of your module. This can lead to 'Dual Package Hazard' issues, such as `instanceof` checks failing if an object created by the CJS version is compared against a class imported from the ESM version.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"First, try deleting your `tsconfig.json` file and letting tshy regenerate it. If errors persist, review the TypeScript upgrade guides for the specific version tshy is now using (e.g., TypeScript 6) to understand breaking changes. Adjust your code or `tsconfig.json` `compilerOptions` accordingly. You can also explicitly install an older, compatible TypeScript version as a `devDependency`.","cause":"TypeScript compilation errors, such as type mismatches or 'Property does not exist' messages, often arise after upgrading tshy because newer TypeScript versions (like TS6, the default for tshy v4+) introduce stricter checks or deprecate older syntax, clashing with existing code or `tsconfig.json` settings.","error":"error TSxxxx: Property 'x' does not exist on type 'y'. Did you mean 'z'?"},{"fix":"Ensure `typescript` is installed as a `devDependency` (`npm i -D typescript`). If you've recently upgraded tshy, delete your `tsconfig.json` and allow tshy to regenerate it. Inspect the full output preceding this error for more specific TypeScript errors (e.g., `TSxxxx` codes) which will pinpoint the exact issue in your source code or configuration.","cause":"This generic error typically indicates that the underlying TypeScript compilation command (`tsc`) failed during tshy's execution. Common causes include an incompatible `tsconfig.json`, missing `typescript` dependency, or syntax errors in your source code.","error":"Error: Command failed with exit code 1: tsc"}],"ecosystem":"npm"}