Plugin Development

For plugin authors — people writing new ttsc plugins. If you just want to use existing plugins like typia or @ttsc/lint, you don’t need this section. Go to TTSC · Using plugins instead.

This chapter is organized in three tiers:

Concepts

Background you need before authoring.

→ Concepts overview

• Plugin protocol — the npm package contract and binary subcommands every ttsc plugin implements.
• AST & Checker — how TypeScript-Go exposes the AST and Checker to Go plugins.

Authoring

The build-and-publish path.

→ Authoring overview

• Getting started — smallest useful transform plugin, end to end.
• Recipes — focused patterns you can copy.
• Testing — Go unit tests + end-to-end ttsc fixtures.
• Publishing — npm package shape and pre-publish checks.
• Local development — go.work, gopls, go test, pnpm notes.

Reference

Deeper material — read as needed.

→ Reference overview

• Architecture — source-plugin build cache and Go toolchain resolution.
• Reference plugin tour — guided walkthrough of banner, strip, paths, and lint, by difficulty.
• Pitfalls — common first-hour failures.
• Workspace release — repository build, test, and release flow.

How a plugin works, in one paragraph

A ttsc plugin is an npm package with two halves: a JS descriptor that lives in the consumer’s node_modules and tells ttsc what the plugin does, and a Go transform that holds the actual logic. The Go transform reads the TypeScript-Go AST, queries the Checker, then either reports diagnostics or rewrites emit. It compiles once into a binary the first time it’s used, and the binary is cached. Plugins run everywhere ttsc runs — CLI, ttsx, ttscserver, every @ttsc/unplugin bundler adapter. One contract, one config (tsconfig.json’s compilerOptions.plugins).

Real code to read

Each first-party plugin is small enough to read end-to-end. Start with banner.

• packages/banner — smallest transform plugin.
• packages/strip — source transform with statement removal.
• packages/paths — transform with tsconfig parsing and Program-backed path resolution.
• packages/lint — diagnostics plugin with Program/Checker access.

Test fixtures that bootstrap a Program for you:

• tests/projects/go-source-plugin-checker — minimal Program/Checker setup.
• tests/projects/go-source-plugin-properties — AST traversal fixture.

Status

v1 protocol, still moving. Don’t publish ttsc as a peer dependency yet — treat it as a build-time-only dependency.

Requirements

• Node.js 18+
• Go 1.22+ (for go test / go vet)
• A consumer test fixture with ttsc and @typescript/native-preview installed.