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/ is a Node --import loader that instruments
./. 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. 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 diffto see what happened andgit 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 . 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 "., 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/ 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:
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 |