ctsc
v1.1.0
Published
A caching compiler for TypeScript monorepos
Downloads
7
Keywords
Readme
ctsc
Experimental caching TypeScript compiler suitable for monorepos and CI.
This acts as a drop-in replacement for TypeScript's own tsc
. It will store the compiled files in a cache directory at $CTSC_CACHE_DIR
(default to /tmp/ctsc
). The next time the compiler is invoked for a particular module, the cached output will be re-used if all the inputs are the same (checked with git hash-object, sha1).
how it differs from tsc project mode
With the introduction of project mode, local caching was added, however, it has 3 significant restrictions:
- it requires that all modules compile with declarations. This means that the toplevel application packages cannot easily be included in the project mode and have to be compiled separately.
- it requires you to specify the dependant projects, even though they can be read from
package.json
. This means double book-keeping. - it only reuses files found in the local directory. This means it cannot be used to speed up compilation in CI by having a shared cache directory containing most of the unchanged modules, precompiled.
ctsc has a different set of limitations, which are somewhat less restrictive:
- it requires the
outDir
setting, so it can more easily cache the output directory properly. This limitation may be removable in the future if we decide to add a filter of the files to copy, as well as use a better copying solution such asrsync
orcpx
(slow) - it requires the
include
setting, so it can more easily read all the inputs. This limitation may also be removable in the future if we decide to add a filter on the files to use when calculating the input hash.
Most monorepo projects already specify an outDir
as build
and include
directories (e.g. src,
tests, etc) so we believe these limitations are ok. Let us know if you disagree.
install
yarn add ctsc
Requirements:
- (windows): WSL - windows subsystem for linux (find, xargs, tail)
- git (for
git hash-object
)
usage
Within a package dir:
ctsc [-p tsconfig.json]
The package must have at least the following configuration in tsconfig:
- include - must be an array of directories or files to include
- compilerOptions.outDir - must exist and be a target output directory
and its workspace dependencies must be referenced in package.json dependencies
or
devDependencies
Then you can use it with wsrun
yarn wsrun --staged -r ctsc
To prune old items from the cache (use env var CTSC_TMP_MAX_ITEMS to limit the cache size)
ctsc --clean
To purge the entire cache
ctsc --purge
how it works
- ctsc calculates two types of hash: input files hash IHASH, and output (type) hash, OHASH
- When ctsc is used to build the package
B
for the first time, a.ctsc.hash
file is inserted into the output, containing theOHASH
- a hash computed from all the outout .d.ts files produced by the compilation. - If package
A
's dependency isB
, the OHASH ofB
from its.ctsc.hash
file is included when calculating the input hashIHASH
hash of packageA
. In addition, all the sources specified ininclude
are also considered when calculating the IHASH. - If this input hash matches a directory in
$CTSC_CACHE_DIR
named$IHASH
,tsc
is not invoked. Instead, the outDir is copied from the cache directly to the destination. - With this scheme, if a depedency has a change in its type definitions, it will propagate a rebuild to all its dependants. If the package doesn't have a types change, a rebuild will not propagate.
- If the dependants themselves end up with a type definition change, rebuild propagation will continue further.
does this mean it can work with dependencies in node_modules too?
Yes! If the dependency was compiled with ctsc, a .ctsc.hash
will be included in the output directory. If this hash of the definition files has changed, any module that depends on that dependency will be rebuilt by ctsc when you install the new version via yarn/npm!