Docs · Getting started

Getting started

This tutorial takes you from zero to a successful apply on a tiny project, using Vitest. You'll instrument code, run it, and watch ts-capture write a real type back into your source.

What you need #

A different setup? Each guide walks the same steps for its own: Jest (Babel) · Svelte · Vite dev server · no bundler (plain Node).

1. Install #

npm install --save-dev @ts-capture/vite @ts-capture/core

2. Register the plugin #

Add ts-capture to your vitest.config.ts:

vitest.config.ts
import { defineConfig } from "vitest/config";
import tsCapture from "@ts-capture/vite";

export default defineConfig({
  plugins: [tsCapture()],
});

The plugin instruments your .ts/.tsx files in memory — your files on disk are not touched during the test run.

3. Start from untyped code #

Say you have this function and a test that exercises it:

src/greet.ts
export function greet(name) {
  return "Hello, " + name;
}
src/greet.spec.ts
import { expect, test } from "vitest";
import { greet } from "./greet";

test("greets", () => {
  expect(greet("World")).toBe("Hello, World");
});

name is implicitly any — that's what we'll fix.

4. Run the tests with collection on #

Point ts-capture at an output directory and run your suite as usual:

TS_CAPTURE_TYPES_DIR=./.ts-capture npm test

After the run, ./.ts-capture/ holds one or more ts-capture-types-<uuid>.json dump files — the runtime observations.

These are working files, not source. Add them to .gitignore:

.gitignore
.ts-capture/
types.json
types.json.applied

5. Merge the dumps #

npx ts-capture merge ./.ts-capture --out types.json

This consolidates every dump into a single types.json.

6. Preview, then apply #

Always preview first:

npx ts-capture apply types.json --dry-run

When the preview looks right, write the changes:

git status --porcelain   # expect no output — nothing uncommitted to lose
npx ts-capture apply types.json
git diff                 # everything ts-capture changed, ready for review

src/greet.ts now carries the observed type:

src/greet.ts (after apply)
export function greet(name: string): string {
  return "Hello, " + name;
}

What you just did #

You ran the full observe → merge → apply pipeline. The type wasn't guessed statically — name became string because the test actually called greet with a string. For the why behind each stage, read How it works.

Next steps #