Docs · Use without a bundler

Use without a bundler

Goal: collect types when you run plain Node — no Vite, Babel, or other transform in the chain (a script, a small CLI, node --experimental-strip-types, etc.). There are two paths; pick by whether you want a one-shot rewrite or the reviewable merge/apply pipeline.

Path A — register (zero-config, one shot) #

@ts-capture/core/register is a Node --import loader that instruments .ts/.tsx files as they load, collects observations, and applies the inferred types straight back to your source on process exit:

node --import @ts-capture/core/register src/app.ts

That single command instruments, runs, and rewrites your source files when the process exits. There is no types.json and no --dry-run preview — it edits in place.

Commit first. This is the least reversible path in ts-capture: your only safety net is source control. Run it on a clean working tree, then git diff to see what happened and git checkout . if you want it gone.

Caveat: register installs a Node ESM loader. Most test runners (Jest, Vitest, mocha+ts-node) install their own loader earlier in the chain and shadow it, so register does not work end-to-end under them — use the matching integration package instead (Vite/Vitest, Jest/Babel), or Path B below.

Needs a Node that runs .ts itself. register instruments TypeScript and hands it back to Node; it does not compile it. That takes Node 22.18 or 23.6 and later, where type stripping is on by default. On Node 20 the run stops at Unknown file extension ".ts", as it would without ts-capture. Type stripping leaves out what needs compiling — enum, namespace with code in it, constructor parameter properties — so a file using them stops at ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX. For either case, use Path B with your own build step, or one of the integration packages.

Path B — preload + manual instrument (reviewable pipeline) #

@ts-capture/core/preload only installs the runtime collector (it writes per-process dumps); it does not instrument your source. Instrument explicitly first, then run with the preload, then use the normal merge/apply pipeline — which gives you --dry-run and config control:

# 1. Instrument the files you want observed (rewrites them — commit first)
npx ts-capture instrument src/app.ts --in-place
# One file per call. For a directory:
#   for file in src/*.ts; do npx ts-capture instrument "$file" --in-place; done

# 2. Run with the collector preloaded
TS_CAPTURE_TYPES_DIR=./.ts-capture \
  NODE_OPTIONS='--require @ts-capture/core/preload' \
  node src/app.ts

# 3. Merge dumps, preview, apply
npx ts-capture merge ./.ts-capture --out types.json
npx ts-capture apply types.json --dry-run
npx ts-capture apply types.json

Instrument the callers as well as the code you want typed, tests included. A function passed in as an argument is typed from what it returns, and that is observed where the function is written: with new Service(() => new Date()) in a test file that was left out, the constructor's clock parameter is seen to be a function and nothing more, and is not annotated. apply skips test files by default, so instrumenting them costs nothing in the result.

Restore the instrumented files (e.g. git checkout) before step 3 so apply lands at the original source offsets — see Don't edit source between observe and apply. Restoring them also keeps ts-capture's runtime hooks out of your commits: the step-1 output is a diagnostic artefact, never something to ship.

Jest with jsdom — use core/setup #

The NODE_OPTIONS preload sets globals on Node's process, which a jest-environment-jsdom worker doesn't inherit (each test file gets a fresh vm context). For that case, install the collector inside the sandbox via setupFilesAfterEnv:

jest.config.js
module.exports = {
  setupFilesAfterEnv: ["@ts-capture/core/setup"],
};

(For the common Jest path, prefer Use with Jest (Babel), where Babel does the instrumentation.)

Which path? #

You want… Use
A quick one-shot rewrite of a script you run with node Path A (register)
A preview (--dry-run), config flags, or the standard pipeline Path B (preload)
To collect under a test runner The runner's integration package, not these

Next #