TypeScript Cached Transpile

Common errors

• Error: Cannot find module 'typescript-cached-transpile'

  cause The package is not installed or not resolvable in the current environment.
  fix Run `npm install typescript-cached-transpile` or `yarn add typescript-cached-transpile`.

• TypeError: create is not a function (when using import { create } from 'typescript-cached-transpile')

  cause The package primarily uses CommonJS `module.exports` and `require` for its `create` function, not ESM named imports.
  fix Use CommonJS syntax: `const { create } = require('typescript-cached-transpile');`

• Builds are not getting faster even with TS_NODE_TRANSPILE_ONLY=true and TS_NODE_COMPILER=typescript-cached-transpile

  cause The caching requirements are not met, causing the cache to be silently skipped.
  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.

Warnings

• gotcha 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.
  Fix: Review the README's requirements list and ensure your `ts-node` configuration adheres to them. Use `tsc --noEmit` for type-checking separately.
• gotcha 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.
  Fix: Be aware of potential interactions with other tools or plugins that modify TypeScript's compiler. Isolate its usage if conflicts arise.
• gotcha 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.
  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`).
• deprecated 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.
  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.

Install

• npm install typescript-cached-transpile npm
• yarn add typescript-cached-transpile yarn
• pnpm add typescript-cached-transpile pnpm

Imports

• create
  wrong:

  import { create } from 'typescript-cached-transpile';

  correct:

  const { create } = require('typescript-cached-transpile');

  The `create` function is used for programmatic customization of the cached compiler and is typically imported via CommonJS `require`.
• module.exports
  wrong:

  export default create(/* options */);

  correct:

  module.exports = create(/* options */);

  When used as a custom `ts-node` compiler, the custom compiler file is expected to `module.exports` the configured compiler instance.

Quickstart

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.

import { readFileSync } from 'fs';
import { join } from 'path';

// Create a dummy TypeScript file for demonstration
const tsContent = `
  interface MyInterface {
    name: string;
    age: number;
  }

  const greeter = (person: MyInterface) => {
    return `Hello, ${person.name}! You are ${person.age} years old.`;
  };

  console.log(greeter({ name: 'Alice', age: 30 }));
`;

// This script demonstrates how to use `typescript-cached-transpile` via ts-node
// For this to run, you'd typically save the above tsContent to a file (e.g., `src/index.ts`)
// and then execute a shell command.

console.log('To run with caching, execute in your terminal:');
console.log('\nTS_NODE_TRANSPILE_ONLY=true TS_NODE_COMPILER=typescript-cached-transpile ts-node src/index.ts');
console.log('\nOr for a custom compiler configuration:');
console.log('// ./my-cached-compiler.js');
console.log('// const { create } = require(\'typescript-cached-transpile\');');
console.log('// module.exports = create({ cacheDir: process.env.TS_CACHED_TRANSPILE_CACHE ?? \'/tmp/ts-cache\' });');
console.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');

console.log('\nEnsure you have ts-node and typescript-cached-transpile installed:');
console.log('npm install -g ts-node typescript typescript-cached-transpile');