Skip to main content

Transpile

Transpile TypeScript and emit compiled output while filtering diagnostics to only project-owned files, keeping strict configs practical in real-world projects.

Summary

The transpile command validates the project's TSConfig, emits compiled JavaScript, and filters source-file emit diagnostics to files owned by the project.

Third-party diagnostics (from node_modules) are excluded so that skipLibCheck: false can be used without surfacing errors in dependencies the project maintainer cannot control.

TSConfig syntax errors and invalid compiler options are always reported before any output is emitted.

Build Without the Noise

Setting skipLibCheck: false in a TSConfig preset catches more bugs, but raw tsc surfaces errors inside third-party packages. This command gives you the emit output without the noise.

Why Use This Command?

  • Emit compiled JavaScript while filtering diagnostics to project-owned files only.
  • Keep skipLibCheck: false in shared TSConfig presets without blocking builds on third-party issues.
  • Produce clear, file-scoped diagnostics with line and column numbers for quick navigation.
  • Replace manual tsc invocations that may report uncontrollable errors during emit.

Use Cases

  • Monorepo builds — Transpile per workspace with each workspace's own tsconfig.json.
  • CI/CD pipelines — Add a transpile step that exits with code 1 on project errors while ignoring dependency noise.
  • Strict TSConfig adoption — Migrate from skipLibCheck: true to false incrementally by surfacing only your own errors during builds.

Requirements

  • Node.js runtime — Use any Node.js LTS release with either the installed nova CLI or npx.
  • TypeScript 6 — Install the supported compiler as a dependency (direct or peer) in the workspace. See TypeScript Compatibility.
  • tsconfig.json — A valid TypeScript configuration file must exist in the workspace (or be specified with --project).

Usage

You can run this command in two ways:

Options

FlagDescription
-p, --project <path>Path to tsconfig.json.

When --project is omitted, the command searches for tsconfig.json starting from the current working directory.

How It Works

  1. Resolve config — Locate the tsconfig.json file from --project or by searching from the current directory.
  2. Validate config — Read and parse the TypeScript configuration, reporting malformed JSON and invalid compiler options before emit.
  3. Create program — Build a full TypeScript program from the parsed file list and compiler options.
  4. Emit — Write compiled output to the configured outDir.
  5. Filter source diagnostics — Keep source-file emit diagnostics owned by your project, exclude source diagnostics in node_modules, and retain every configuration diagnostic.
  6. Report — Print each error with file path, line, column, and message, then exit with code 1 if any errors remain.

Non-Zero Exit Code

The command exits with code 1 when the TSConfig is invalid or project-owned emit errors are found. CI pipelines that use this command will fail the step on either problem.

Examples

Troubleshooting

  • No tsconfig.json found — Confirm a tsconfig.json exists in the current directory, or pass the correct path with --project.
  • TypeScript not installed or unsupported — Install the supported compiler with npm install --save-dev [email protected].
  • Invalid TSConfig but no source location — Compiler-option diagnostics can apply to the whole tsconfig.json, so TypeScript may report the message without a source line and column.
  • Zero errors but build fails — This command only handles emit; other build errors from bundlers or other tools are not covered.
  • Errors in generated files — If generated files (e.g., .docusaurus) appear in diagnostics, add them to the exclude array in your tsconfig.json.