tsickle

library0.46.3jsnpmunverified

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.

devops

npm install tsickle

github ↗package ↗

INSTALL

IMPORT

SIG · TSICKLE

tsickle

devopsjavascriptv0.46.3

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

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

✓ npx tsickle -p tsconfig.json

✗ node_modules/tsickle/src/cli.js

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.

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.

Debug

Known issues

breakingThe 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.

affects: >=0.1.0

breakingTsickle 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.

affects: >=0.1.0

gotchaTsickle'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.

affects: >=0.1.0

gotchaStrict 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).

affects: >=0.30.0

gotchaThe `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.

affects: >=0.1.0

Errors

Common errors & fixes

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

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.

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

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.

Upgrade

Version history

0.46.3latest on npm

Audit

Dependencies

typescriptrequiredRequired peer dependency for TypeScript compilation features, typically specified with a tilde range like `~4.7.2`.

Agent activity

6 hits · last 30 days

node

Resources

githubhttps://github.com/angular/tsickle ↗

packagehttps://www.npmjs.com/package/tsickle ↗