{"id":12779,"library":"typescript-cached-transpile","title":"TypeScript Cached Transpile","description":"typescript-cached-transpile is a utility designed to accelerate TypeScript compilation in `transpileOnly` mode by monkey-patching the `typescript` compiler's `transpileModule` function to utilize a disk cache. It is currently at version 0.0.6, indicating an early development stage, and its release cadence is likely tied to the maintainer's personal monorepo updates. Its primary differentiator is its targeted optimization for `ts-node`'s `transpileOnly` mode, significantly reducing build times for repetitive compilations of unchanged files by persisting transpilation results to disk. It transparently integrates by being specified as `ts-node`'s compiler, and offers configuration via environment variables or a custom JS file for cache directory and portable cache settings. It explicitly states limitations, such as not working with transformers, diagnostics, or type-checking.","status":"active","version":"0.0.6","language":"javascript","source_language":"en","source_url":"https://github.com/cspotcode/personal-monorepo","tags":["javascript"],"install":[{"cmd":"npm install typescript-cached-transpile","lang":"bash","label":"npm"},{"cmd":"yarn add typescript-cached-transpile","lang":"bash","label":"yarn"},{"cmd":"pnpm add typescript-cached-transpile","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency; the package monkey-patches the `typescript` compiler itself.","package":"typescript","optional":false}],"imports":[{"note":"The `create` function is used for programmatic customization of the cached compiler and is typically imported via CommonJS `require`.","wrong":"import { create } from 'typescript-cached-transpile';","symbol":"create","correct":"const { create } = require('typescript-cached-transpile');"},{"note":"When used as a custom `ts-node` compiler, the custom compiler file is expected to `module.exports` the configured compiler instance.","wrong":"export default create(/* options */);","symbol":"module.exports","correct":"module.exports = create(/* options */);"}],"quickstart":{"code":"import { readFileSync } from 'fs';\nimport { join } from 'path';\n\n// Create a dummy TypeScript file for demonstration\nconst tsContent = `\n  interface MyInterface {\n    name: string;\n    age: number;\n  }\n\n  const greeter = (person: MyInterface) => {\n    return `Hello, ${person.name}! You are ${person.age} years old.`;\n  };\n\n  console.log(greeter({ name: 'Alice', age: 30 }));\n`;\n\n// This script demonstrates how to use `typescript-cached-transpile` via ts-node\n// For this to run, you'd typically save the above tsContent to a file (e.g., `src/index.ts`)\n// and then execute a shell command.\n\nconsole.log('To run with caching, execute in your terminal:');\nconsole.log('\\nTS_NODE_TRANSPILE_ONLY=true TS_NODE_COMPILER=typescript-cached-transpile ts-node src/index.ts');\nconsole.log('\\nOr for a custom compiler configuration:');\nconsole.log('// ./my-cached-compiler.js');\nconsole.log('// const { create } = require(\\'typescript-cached-transpile\\');');\nconsole.log('// module.exports = create({ cacheDir: process.env.TS_CACHED_TRANSPILE_CACHE ?? \\'/tmp/ts-cache\\' });');\nconsole.log('\\nTS_NODE_TRANSPILE_ONLY=true TS_NODE_COMPILER=$PWD/my-cached-compiler.js TS_CACHED_TRANSPILE_CACHE=$PWD/.cache ts-node src/index.ts');\n\nconsole.log('\\nEnsure you have ts-node and typescript-cached-transpile installed:');\nconsole.log('npm install -g ts-node typescript typescript-cached-transpile');\n","lang":"typescript","description":"Demonstrates the command-line usage of `typescript-cached-transpile` with `ts-node` for faster `transpileOnly` execution, including how to use a custom compiler file and specify a cache directory."},"warnings":[{"fix":"Review the README's requirements list and ensure your `ts-node` configuration adheres to them. Use `tsc --noEmit` for type-checking separately.","message":"Caching only works if specific requirements are met, including no transformers, no diagnostics returned, same compiler version, same filename, same source code, sourcemaps enabled, and same config object. If these are not met, caching is silently skipped, leading to no performance improvement.","severity":"gotcha","affected_versions":">=0.0.1"},{"fix":"Be aware of potential interactions with other tools or plugins that modify TypeScript's compiler. Isolate its usage if conflicts arise.","message":"The package monkey-patches the TypeScript compiler. This can lead to unexpected behavior or conflicts with other tools that also modify TypeScript's internal functions.","severity":"gotcha","affected_versions":">=0.0.1"},{"fix":"Always set `TS_CACHED_TRANSPILE_PORTABLE=true` when creating or consuming a cache intended for distribution or relocation. Ensure cache directory paths are absolute (e.g., `$PWD/.cache`).","message":"When using a portable cache, `TS_CACHED_TRANSPILE_PORTABLE=true` must be set. This changes how filenames are stored in cache keys from absolute to relative paths. Forgetting this will make pre-generated caches non-portable.","severity":"gotcha","affected_versions":">=0.0.1"},{"fix":"Monitor `ts-node` and `typescript` updates for breaking changes to their compiler API or custom compiler integration points. Be prepared for potential refactoring if underlying APIs change.","message":"The package is in early stages (v0.0.6) and is intended for a very specific use case with `ts-node`'s `transpileOnly` mode. Its direct integration method via `TS_NODE_COMPILER` is somewhat unconventional and might not be supported in future `ts-node` versions or other build tools.","severity":"deprecated","affected_versions":">=0.0.1"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Run `npm install typescript-cached-transpile` or `yarn add typescript-cached-transpile`.","cause":"The package is not installed or not resolvable in the current environment.","error":"Error: Cannot find module 'typescript-cached-transpile'"},{"fix":"Use CommonJS syntax: `const { create } = require('typescript-cached-transpile');`","cause":"The package primarily uses CommonJS `module.exports` and `require` for its `create` function, not ESM named imports.","error":"TypeError: create is not a function (when using import { create } from 'typescript-cached-transpile')"},{"fix":"Verify that no transformers are used, no diagnostics are returned, sourcemaps are enabled, and the config object and source code remain consistent. Ensure you are not relying on type-checking, which this package does not accelerate.","cause":"The caching requirements are not met, causing the cache to be silently skipped.","error":"Builds are not getting faster even with TS_NODE_TRANSPILE_ONLY=true and TS_NODE_COMPILER=typescript-cached-transpile"}],"ecosystem":"npm"}