ts-syntax-error

Check TypeScript source code for syntax and type errors programmatically

Overview

Type annotations are stripped at runtime by runtimes like Node (via --experimental-strip-types) or Bun, so most TypeScript type errors won't surface there. This library is for tooling — linters, editors, build pipelines, or anyone who needs to verify TypeScript source at the API level.

Install

npm install ts-syntax-error
# or
bun add ts-syntax-error

typescript is a regular dependency and is bundled. no separate install needed.

Usage

check(source, filename?, options?)

Returns the first TSSyntaxError found in source, or null if the source is valid.

import { check } from "ts-syntax-error";

const err = check(`const x: = 5;`, "example.ts");

if (err) {
  console.error(err.annotated);
}

Output:

example.ts:1:10
'string', 'number', ... or another valid type expected.

> const x: = 5;
          ^

checkAll(source, filename?, options?)

Same as check, but returns all errors as an array (empty array if none).

import { checkAll } from "ts-syntax-error";

const errors = checkAll(source, "index.ts");
errors.forEach(err => console.error(err.annotated));

Options

interface CheckOptions {
  target?:     ScriptTarget;  // "ES2020" (default)
  module?:     ModuleKind;    // "CommonJS" (default)
  jsx?:        JsxMode;       // "None" (default)
  strict?:     boolean;       // false (default)
  checkTypes?: boolean;       // false (default)
  allowJs?:    boolean;       // false (default)
  pedantic?:   boolean;       // false (default)
}

| Option | Default | Description | |---|---|---| | target | "ES2020" | TypeScript compilation target ("ES5", "ES2022", "ESNext", …) | | module | "CommonJS" | Module system ("ESNext", "Node16", "NodeNext", …) | | jsx | "None" | JSX mode ("React", "ReactJSX", "Preserve", …) | | strict | false | Enable strict type-checking flags (only meaningful with checkTypes) | | checkTypes | false | Also report semantic / type errors, not just syntax | | allowJs | false | Allow .js files to be processed | | pedantic | false | Report unused variables, missing returns, etc. (requires checkTypes) |

Type checking example

import { check } from "ts-syntax-error";

const err = check(
  `const x: string = 123;`,
  "index.ts",
  { checkTypes: true, strict: true }
);

if (err) {
  console.error(err.annotated);
  console.log(err.isTypeError); // true
}

JSX / TSX example

const err = check(
  `const el = <div className={42}>hello</div>;`,
  "App.tsx",
  { jsx: "ReactJSX", checkTypes: true }
);

License

MIT