Internals: Build and Cache

This page is for debugging source plugin builds.

Cold Build Path

When ttsc sees a plugin source descriptor:

Resolve source.
Hash the plugin source and host versions.
Reuse the cached binary on hit.
Copy source into a scratch directory on miss.
Generate a go.work overlay pointing at ttsc and its shims.
Run go build -o plugin <entry>.
Move the binary into the cache.
Invoke the binary with check, transform, or build.

Cache Key Inputs

The cache key includes:

ttsc package version.
resolved @typescript/native-preview version.
platform and architecture.
resolved source entry.
files under the plugin source directory, except skipped generated/cache directories and editor backup files ending in ~.
the same hashable files under the local ttsc and shim overlay directories used for the generated go.work.

The cache key does not include:

consumer TypeScript source files;
plugin options such as lint rules / extends, banner, or calls;
CLI flags such as --emit or --outDir;

README, JSON, schema, and other data files inside the plugin source directory do affect the cache key. This keeps //go:embed and other file-backed plugin data aligned with the built binary. Local workspace changes to ttsc’s Go host or shim overlay also invalidate the source plugin cache automatically.

Cache Locations

Default:


<project>/node_modules/.ttsc/plugins/<key>/plugin
<project>/.ttsc/plugins/<key>/plugin

Override:


TTSC_CACHE_DIR=/tmp/ttsc-cache npx ttsc --emit

Clean:


npx ttsc clean

Go Toolchain Resolution

ttsc resolves Go in this order:

TTSC_GO_BINARY, when set.
the installed @ttsc/{platform}-{arch} package’s bundled Go SDK.
local workspace fallback under ttsc/native/go.
go on PATH.

Published consumer installs should use the bundled Go SDK. go on PATH is mainly a development fallback.

Debugging Build Failures

If go build fails, ttsc prints the Go stderr:


ttsc: building plugin "my-plugin" via "go build" failed:
go-plugin/main.go:42:8: undefined: shimast.Something

Check:

missing shim require in go.mod;
missing source files in the npm tarball;
wrong source directory or package entry;
stale cache, fixed with npx ttsc clean;
pnpm local dev layout, fixed in Local Development.

Concurrency

Concurrent ttsc processes may build the same missing key at the same time. Scratch directories are unique, and the final move is atomic. This is wasteful but safe.