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 uses the TypeScript compiler API to call program.emit() against a project, then filters the emit diagnostics to only include errors in 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.

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 — Must be installed as a dependency (direct or peer) in the workspace.
  • 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:

# Original
nova utility transpile

# Shorthand
nova util xpile

Note: If Nova is installed only locally (inside a project), the command will work only within that project's directory. See the npm docs for details.

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. Parse config — Read and parse the TypeScript configuration using the compiler API.
  3. Create program — Build a full TypeScript program from the parsed file list and compiler options.
  4. Emit — Call program.emit() to write compiled output to the configured outDir.
  5. Filter — Keep only emit diagnostics where the source file starts with the current working directory and does not contain node_modules in its path.
  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 project-owned emit errors are found. CI pipelines that use this command will fail the step on errors.

Examples​

Default (auto-detect tsconfig.json)
# Original
nova utility transpile

# Shorthand
nova util xpile
Custom tsconfig path
# Original
nova utility transpile --project ./tsconfig.build.json

# Shorthand
nova util xpile -p ./tsconfig.build.json

Troubleshooting​

  • No tsconfig.json found — Confirm a tsconfig.json exists in the current directory, or pass the correct path with --project.
  • TypeScript not installed — The command requires TypeScript as a dependency. Run npm install typescript if it is missing.
  • 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.