tshy - TypeScript Hybridizer

4.1.1 · active · verified Sun Apr 19

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.

Common errors

```
error TSxxxx: Property 'x' does not exist on type 'y'. Did you mean 'z'?
```
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.

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`.
```
Error: Command failed with exit code 1: tsc
```
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.

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.

Warnings

breaking 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.
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`).
gotcha 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.
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.

Install

npm install tshy npm
yarn add tshy yarn
pnpm add tshy pnpm

Imports

(CLI tool)
wrong:
```
import tshy from 'tshy'; // tshy is not a library for direct import into application code
```
correct:
```
n/a (tshy is executed as a command-line tool, typically via npm scripts)
```
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.

Quickstart

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.

{
  // package.json
  "name": "my-hybrid-package",
  "version": "1.0.0",
  "description": "A package built with tshy",
  "main": "dist/commonjs/index.js",
  "type": "commonjs", // or module
  "files": [
    "dist"
  ],
  "scripts": {
    "build": "tshy",
    "prepare": "npm run build" // Runs tshy on npm install
  },
  "devDependencies": {
    "tshy": "^4.0.0",
    "typescript": "^5.2.2" // Optional: specify your TS version
  },
  "exports": {},
  "types": "dist/commonjs/index.d.ts"
}

// src/index.ts
export const greet = (name: string): string => {
  return `Hello, ${name}! This is a hybrid module built by tshy.`;
};

export class Greeter {
  private message: string;
  constructor(name: string) {
    this.message = `Greetings from ${name}.`;
  }
  sayHello(): string {
    return this.message;
  }
}

// To run this quickstart:
// 1. Create a new directory and `npm init -y`
// 2. Paste the package.json content above.
// 3. Create a `src/index.ts` file with the content above.
// 4. Run `npm install` (this will trigger the 'prepare' script).
// 5. Observe 'dist/commonjs' and 'dist/esm' directories, and updated 'exports' in package.json.

view raw JSON →