realapi-check

Catch AI-hallucinated imports, methods and options before they reach runtime.

AI coding assistants write code for the library version they were trained on, not the one you installed. They invent functions, misspell methods, pass options that were removed, and import packages that don't exist. realapi checks your code against the exact package versions in your node_modules and tells you what isn't real.

$ npx realapi-check

src/user.ts
  7:22     error    'emial' does not exist on ZodString ([email protected]). Did you mean 'email'?  missing-member
                    const s = z.string().emial();
  9:34     error    'retries' is not a known option of AxiosRequestConfig ([email protected])  unknown-option
                    axios.get("/x", { timeout: 1000, retries: 3 });
  3:10     error    'readFileAsync' is not exported by @types/[email protected]. Did you mean 'readFileSync'?  missing-export
                    import { readFileAsync } from "node:fs";
  5:32     error    'express-useragent-pro' does not exist on npm. It was probably invented; do not install it blindly  missing-package
                    import { parseUserAgent } from "express-useragent-pro";
  10:29    warning  'merge' is deprecated in [email protected]: Use A.extend(B.shape) instead.  deprecated
                    const merged = a.merge(b);

✖ 5 problems (4 errors, 1 warning) checked 42 files against 12 installed packages

What it catches

| Kind | Example | |---|---| | missing-export | import { groupByKey } from "lodash", const { makeClient } = require("x") | | missing-member | app.listenAsync(), z.string().emial() | | unknown-option | axios.get(url, { retries: 3 }) | | missing-package | Importing a package that isn't installed. With --online, it also checks whether the package exists on npm at all. | | deprecated (warning) | APIs marked @deprecated in your installed version, with the suggested replacement |

It works on TypeScript and plain JavaScript (import and require), with or without a tsconfig.json.

Why not just run tsc?

• JavaScript projects don't have tsc checking them at all. realapi type-checks JS against the packages' own type definitions.
• It reports only package API problems. A tsc run on a large project can print hundreds of unrelated errors. realapi keeps only the ones where your code uses something a package doesn't provide.
• Readable output. Each problem names the package and the installed version, suggests the closest real name, and separates "not installed" from "doesn't exist".
• It's honest about coverage. Packages that ship no types are listed as not verified, rather than silently passing.

Usage

npx realapi-check              # check the whole project
npx realapi-check src/ scripts/ # check specific paths
npx realapi-check --json       # machine-readable output for CI or AI agents
npx realapi-check --online     # also look up missing packages on the npm registry

Installed as a dev dependency (npm i -D realapi-check), the command is also available under the shorter name realapi.

| Option | Description | |---|---| | -p, --project <file> | tsconfig/jsconfig to use (auto-detected by default) | | --json | Print results as JSON | | --online | Check missing packages against registry.npmjs.org | | --no-deprecated | Don't report deprecated APIs | | --strict | Exit with code 1 on warnings too |

Exit codes: 0 clean, 1 problems found, 2 usage or runtime error.

Ignoring a line

// realapi-ignore
client.addedAtRuntimeByAPlugin();

In CI

- run: npm ci
- run: npx realapi-check

With AI agents

Add this to your agent instructions (AGENTS.md, CLAUDE.md, .cursorrules):

After changing code, run npx realapi-check --json and fix every reported issue before finishing.

The JSON output includes the file, line, symbol, package, version and suggestion for each problem, so an agent can fix its own mistakes.

Programmatic API

import { check, formatPretty } from "realapi-check";

const result = await check({ cwd: process.cwd(), paths: ["src"] });
console.log(formatPretty(result));
// result.issues, result.packagesChecked, result.unverifiable

How it works

realapi builds a TypeScript program over your project with allowJs and checkJs enabled, using your tsconfig.json settings when one exists. It takes the compiler's "does not exist" diagnostics and keeps only those whose target type is declared inside node_modules. That covers packages' own types, @types/*, and the Node built-ins. Your own code, TypeScript's standard library, and shapes derived from your data (such as z.infer<...>) are ignored, so it reports only real mismatches with package APIs. Module augmentation (declare module "express" { ... }) and tsconfig paths aliases are respected.

Limitations

• Packages without type definitions can't be verified. They are listed in the summary.
• .vue, .svelte and .astro files aren't checked yet.
• In monorepos, run it once per package so each one uses its own tsconfig.json.
• Properties your own code assigns (app.db = pool, req.user = decoded) are treated as yours and never reported. Properties added by a third-party plugin that ships no types will be reported; add types for them or use // realapi-ignore.
• With a tsconfig.json, the files checked are the ones its include/exclude select. As with tsc, a .js file next to a .ts file with the same name is treated as build output and skipped.

License

MIT