Tsickle: TypeScript to Closure Translator

Common errors

• Package "tsickle" has an incompatible peer dependency to "typescript" (requires "~X.Y.Z", would install "A.B.C").

  cause The installed TypeScript version (A.B.C) does not match the version range required by Tsickle (~X.Y.Z).
  fix Install the TypeScript version compatible with your Tsickle installation. For `tsickle@0.46.3`, run `npm install typescript@4.7.2`.

• error TS2307: Cannot find module '...' or its corresponding type declarations.

  cause The `tsconfig.json` file is not correctly configured to include all source files, or module resolution paths are incorrect for your project structure.
  fix Review the `include`, `exclude`, and `paths` options in your `tsconfig.json`. Ensure all relevant `.ts` files and their dependencies are discoverable by the TypeScript compiler when Tsickle is run.

• Error: unknown argument: --some-unsupported-arg

  cause An unrecognized or deprecated command-line argument was passed to the `tsickle` CLI. CLI options can change between versions.
  fix Run `npx tsickle --help` to view the available command-line options for your installed Tsickle version and update your build scripts accordingly.

Warnings

• breaking The Tsickle repository is officially unsupported since November 2022, with no new commits to master since December 2023, and was frozen starting May 2024. It will not be updated.
  Fix: Migrate away from Tsickle. For Angular projects, the Angular CLI and `@angular/compiler-cli` handle Closure Compiler compatibility internally for many use cases, or explore alternative transpilation and optimization strategies.
• breaking Tsickle converts ES6 modules into Closure's `goog.module` system. This is a fundamental transformation that impacts module loading and compatibility with other JavaScript environments.
  Fix: Ensure that your downstream build tools and runtime environment (e.g., Closure Compiler) are configured to correctly consume and execute `goog.module` formatted code. Do not expect standard ES module output.
• gotcha Tsickle's output JavaScript is specifically designed as an intermediate form for the Closure Compiler and is not intended for human readability. It can appear 'ugly' due to heavy JSDoc annotations and transformations.
  Fix: Treat Tsickle's output as an artifact that feeds directly into Closure Compiler, not as final source code to be manually inspected or debugged. Debug TypeScript source or Closure Compiler's final output.
• gotcha Strict peer dependency on specific TypeScript versions. Using an incompatible TypeScript version can lead to compilation errors or unexpected behavior. For instance, `tsickle@0.46.3` requires `typescript@~4.7.2`.
  Fix: Always install the exact or compatible TypeScript version specified in Tsickle's `peerDependencies`. Use `npm install typescript@~X.Y.Z` (where X.Y.Z is the required version).
• gotcha The `declare` keyword in TypeScript (or `.d.ts` files) is crucial for Tsickle to inform Closure Compiler which names must be preserved during minification. Neglecting `declare` for external interfaces or JSON properties can lead to runtime errors due to name mangling.
  Fix: Consistently use `declare` for interfaces, classes, and properties that interact with external systems or are part of a public API where name preservation is critical. Review Closure Compiler's externs and renaming policies.

Install

• npm install tsickle npm
• yarn add tsickle yarn
• pnpm add tsickle pnpm

Imports

• runTsickle

  import { runTsickle } from 'tsickle';

  This is a programmatic API primarily used by build tool wrappers; direct use requires setting up a `ts.Program` and `ts.CompilerHost`. Not typically used by end-user applications.
• Options

  import { Options } from 'tsickle';

  This interface defines configuration parameters for `runTsickle` and other programmatic functions within Tsickle.
• Tsickle CLI
  wrong:

  node_modules/tsickle/src/cli.js

  correct:

  npx tsickle -p tsconfig.json

  While Tsickle can be executed directly via its `cli.js`, it's recommended to use `npx tsickle` or define it as a script in `package.json` for proper path resolution and version management.

Quickstart

Demonstrates how to use the Tsickle CLI to transpile a simple TypeScript project, generating Closure-annotated JavaScript output in the `dist` directory. This setup includes a `tsconfig.json` and a `package.json` script for execution.

{
  "name": "tsickle-demo",
  "version": "1.0.0",
  "scripts": {
    "build:tsickle": "npx tsickle -p tsconfig.json"
  },
  "devDependencies": {
    "tsickle": "^0.46.3",
    "typescript": "~4.7.2"
  }
}
// tsconfig.json
{
  "compilerOptions": {
    "target": "es2017",
    "module": "esnext",
    "outDir": "dist",
    "declaration": true,
    "strict": true,
    "lib": ["es2017"],
    "allowJs": true
  },
  "include": ["src/**/*.ts"]
}
// src/greeter.ts
/**
 * @fileoverview A simple class to demonstrate Tsickle conversion.
 */
export class Greeter {
  /** @type {string} */
  private readonly name: string;

  /**
   * @param {string} name The name to greet.
   */
  constructor(name: string) {
    this.name = name;
  }

  /**
   * Generates a greeting message.
   * @return {string} The greeting.
   */
  greet(): string {
    return `Hello, ${this.name}!`;
  }
}

// To run this example:
// 1. Create the files above in your project root.
// 2. Run `npm install`
// 3. Run `npm run build:tsickle`
// This will output Closure-annotated JavaScript to the `dist` directory.