CLI & Scripts

ttsc compiles, ttsx runs. This page wires them into package.json scripts and CI; the full flag reference is in Compiler (ttsc) and Execute (ttsx).

package.json scripts

// package.json
{
  "scripts": {
    "build": "ttsc",
    "dev": "ttsc --watch",
    "check": "ttsc --noEmit",
    "fix": "ttsc fix",
    "format": "ttsc format",
    "start": "ttsx src/index.ts"
  }
}

ttsc reads tsconfig.json from the current directory. A different config is -p tsconfig.build.json, a different output directory is --outDir build.

fix applies every fixable lint violation plus format edits, then re-checks. format applies only the edits that cannot change behavior, so it is safe for a pre-commit hook.

Watch mode

npx ttsc --watch

Re-compiles on save. Add --preserveWatchOutput to keep your scrollback.

The watcher follows the compiler’s resolved program inputs. New included folders and referenced config or declaration inputs join the session as the project changes, while compiler output and cache products do not trigger another build. Check-stage plugins can additionally publish exact local files and glob populations; those declared inputs stay live through missing files and empty populations without making unrelated documents rebuild the project.

ttsc check --watch also keeps capable check-stage sidecars and their no-emit Programs resident across normal source saves and declared external-data updates. Config, compiler-root, plugin, Go-contributor, and declared-input topology changes start a fresh session, while unsupported plugins continue through the one-shot path.

CI

- run: npx ttsc --noEmit

Type errors and lint violations fail the same step, so there is no second lint job drifting out of sync with the build.

Go-source plugins compile to native binaries once, then live in a cache. Cache the directories that ttsc cache paths --json prints, and warm them with ttsc prepare, so CI stops rebuilding them every run.

One-off scripts with ttsx

ttsx is for the file you want to run, not ship: seeders, migrations, experiments. It type-checks the whole project first, then executes natively, so a broken script fails at the check instead of halfway through your database.

Arguments after -- go to the script untouched, and -r preloads modules Node-style:

npx ttsx src/server.ts -- --port 3000
npx ttsx -r dotenv/config src/index.ts

Workspace dependencies that ship raw TypeScript load fine; the module hooks behind that are in Execute (ttsx).