nyc — JavaScript Code Coverage Tool Built on Istanbul

Introduction

nyc is the command-line interface for Istanbul, the standard JavaScript code coverage instrumentation library. It wraps any Node.js process, instruments the source code at runtime, and produces detailed reports showing which lines, branches, functions, and statements were executed during a test run.

What nyc Does

• Instruments JavaScript and TypeScript source files to track execution paths
• Generates coverage reports in multiple formats (text, HTML, lcov, JSON, Cobertura)
• Integrates with any test runner that runs in Node.js (Mocha, AVA, Tape, etc.)
• Supports ES module and CommonJS source code with source map awareness
• Enforces minimum coverage thresholds as part of CI pipelines

Architecture Overview

nyc uses Istanbul's instrumentation library to insert counters into the abstract syntax tree of each source file before execution. When the instrumented code runs, counters record hits for every statement, branch, and function. After the process exits, nyc collects the raw coverage data and feeds it to Istanbul's reporting engine, which merges results and renders them in the requested format.

Self-Hosting & Configuration

• Install as a dev dependency via npm or yarn
• Configure via .nycrc, .nycrc.json, or the nyc section in package.json
• Set include/exclude globs to control which files are instrumented
• Enable source map support for transpiled TypeScript or Babel code
• Add coverage threshold checks (--branches, --lines, --functions, --statements) for CI enforcement

Key Features

• Multiple report formats including interactive HTML, terminal summary, and CI-compatible lcov
• Source map support for accurate coverage of transpiled and bundled code
• Subprocess coverage collection for forked or spawned Node.js processes
• Configurable thresholds that fail the build when coverage drops below targets
• Per-file and per-directory coverage breakdown for targeted improvement

Comparison with Similar Tools

• c8 — V8-native coverage without instrumentation; faster but limited to V8-based runtimes
• Jest coverage — built into Jest; nyc works with any test runner
• Vitest coverage — built into Vitest using v8 or Istanbul; nyc is framework-independent
• Codecov / Coveralls — cloud reporting services; nyc generates the coverage data they consume
• Blanket.js — older instrumentation tool; nyc and Istanbul are the maintained standard

FAQ

Q: What is the difference between nyc and Istanbul? A: Istanbul is the instrumentation and reporting library. nyc is the CLI that wraps your test command and orchestrates Istanbul under the hood.

Q: Does nyc work with TypeScript? A: Yes. Enable source maps in your TypeScript compiler, and nyc will map coverage back to the original .ts files.

Q: Can nyc merge coverage from multiple test runs? A: Yes. Use nyc merge to combine coverage JSON files from parallel or sequential runs into a single report.

Q: Is nyc still actively maintained? A: nyc is in maintenance mode. For new projects using V8-based runtimes, c8 is the recommended alternative. nyc remains reliable for existing setups.

Sources

• https://github.com/istanbuljs/nyc
• https://istanbul.js.org/