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 compiler diagnostics to files owned by the project. Pass --watch to keep the same filtered emitter running as files change.

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.

Why Use This Command?

• Emit compiled JavaScript while filtering diagnostics to project-owned files only.
• Use the same filtering contract for one-shot production builds and incremental development watches.
• 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.
• Development watch — Re-emit changed TypeScript without bringing third-party node_modules diagnostics back into the terminal.

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

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

Watch mode performs an initial emit, keeps the TypeScript watcher alive, and reruns the same project-owned diagnostic filter after each change. Stop it with Control + C.

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, or create an incremental builder in watch mode.
4. Emit — Write compiled output to the configured outDir without forcing skipLibCheck.
5. Filter diagnostics — Keep pre-emit and 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. One-shot mode exits with code 1 if any errors remain; watch mode stays alive for the next edit.

Examples

Watch a Project

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.
• Watch mode does not exit — This is expected. The watcher stays active until you stop it with Control + C.