{"id":15249,"library":"tsickle","title":"Tsickle: TypeScript to Closure Translator","description":"Tsickle is a TypeScript transpiler designed to convert TypeScript code into JavaScript with Closure Compiler-compatible JSDoc annotations and module formats (`goog.module`). It serves as an intermediate step in build pipelines that leverage Closure Compiler for advanced optimization and minification, particularly within large-scale applications like those developed by Google and Angular. The current stable version is 0.46.3, and its release cadence is irregular, tied to Angular's development and internal Google needs. Key differentiators include its specialized handling of TypeScript types for Closure's type system, conversion of ES6 modules to `goog.module`, and generation of externs.js from TypeScript definition files, making TypeScript projects amenable to the unique optimization strategies of Closure Compiler. It is explicitly noted as a library intended for integration into larger build systems rather than direct end-user application development, often requiring downstream compatibility with Closure's specific module and type conventions.","status":"abandoned","version":"0.46.3","language":"javascript","source_language":"en","source_url":"https://github.com/angular/tsickle","tags":["javascript","typescript","closure"],"install":[{"cmd":"npm install tsickle","lang":"bash","label":"npm"},{"cmd":"yarn add tsickle","lang":"bash","label":"yarn"},{"cmd":"pnpm add tsickle","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required peer dependency for TypeScript compilation features, typically specified with a tilde range like `~4.7.2`.","package":"typescript","optional":false}],"imports":[{"note":"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.","symbol":"runTsickle","correct":"import { runTsickle } from 'tsickle';"},{"note":"This interface defines configuration parameters for `runTsickle` and other programmatic functions within Tsickle.","symbol":"Options","correct":"import { Options } from 'tsickle';"},{"note":"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.","wrong":"node_modules/tsickle/src/cli.js","symbol":"Tsickle CLI","correct":"npx tsickle -p tsconfig.json"}],"quickstart":{"code":"{\n  \"name\": \"tsickle-demo\",\n  \"version\": \"1.0.0\",\n  \"scripts\": {\n    \"build:tsickle\": \"npx tsickle -p tsconfig.json\"\n  },\n  \"devDependencies\": {\n    \"tsickle\": \"^0.46.3\",\n    \"typescript\": \"~4.7.2\"\n  }\n}\n// tsconfig.json\n{\n  \"compilerOptions\": {\n    \"target\": \"es2017\",\n    \"module\": \"esnext\",\n    \"outDir\": \"dist\",\n    \"declaration\": true,\n    \"strict\": true,\n    \"lib\": [\"es2017\"],\n    \"allowJs\": true\n  },\n  \"include\": [\"src/**/*.ts\"]\n}\n// src/greeter.ts\n/**\n * @fileoverview A simple class to demonstrate Tsickle conversion.\n */\nexport class Greeter {\n  /** @type {string} */\n  private readonly name: string;\n\n  /**\n   * @param {string} name The name to greet.\n   */\n  constructor(name: string) {\n    this.name = name;\n  }\n\n  /**\n   * Generates a greeting message.\n   * @return {string} The greeting.\n   */\n  greet(): string {\n    return `Hello, ${this.name}!`;\n  }\n}\n\n// To run this example:\n// 1. Create the files above in your project root.\n// 2. Run `npm install`\n// 3. Run `npm run build:tsickle`\n// This will output Closure-annotated JavaScript to the `dist` directory.\n","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=0.1.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=0.1.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"},{"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).","message":"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`.","severity":"gotcha","affected_versions":">=0.30.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Install the TypeScript version compatible with your Tsickle installation. For `tsickle@0.46.3`, run `npm install typescript@4.7.2`.","cause":"The installed TypeScript version (A.B.C) does not match the version range required by Tsickle (~X.Y.Z).","error":"Package \"tsickle\" has an incompatible peer dependency to \"typescript\" (requires \"~X.Y.Z\", would install \"A.B.C\")."},{"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.","cause":"The `tsconfig.json` file is not correctly configured to include all source files, or module resolution paths are incorrect for your project structure.","error":"error TS2307: Cannot find module '...' or its corresponding type declarations."},{"fix":"Run `npx tsickle --help` to view the available command-line options for your installed Tsickle version and update your build scripts accordingly.","cause":"An unrecognized or deprecated command-line argument was passed to the `tsickle` CLI. CLI options can change between versions.","error":"Error: unknown argument: --some-unsupported-arg"}],"ecosystem":"npm"}