Quickstart

At the end of this page you have scanned your own repository, you know how to read what jscpd prints, and the scan fails your build when duplication grows. Every output below comes from fixtures/mcp-demo in the jscpd repository, a small JavaScript project with three copied blocks; yours will show your files.

Before you start

One of these on the machine: a POSIX shell with curl (macOS, Linux), Node.js 18 or newer, Python with pip, or Rust with cargo. Windows users take the PowerShell installer from the installation page.

1. Install

curl -fsSL https://jscpd.dev/install.sh | bash   # macOS and Linux: one binary, no runtime
npx jscpd --version                               # or no install at all, with Node.js

jscpd 5.4.0

The installation page lists npm, pip, cargo, Homebrew, nix and Docker.

2. Scan

Run jscpd in the directory you want to scan. Without options it reports exact copies of at least 5 lines and 50 tokens, skips whatever .gitignore skips, and prints the clones followed by a table per format.

jscpd .

Clone found (javascript)
 - src/invoice.js [1:1 - 6:72] (6 lines, 105 tokens)
   src/print/invoice.js [1:1 - 6:72]
Clone found (javascript)
 - src/invoice.js [6:71 - 12:2] (7 lines, 93 tokens)
   src/print/invoice.js [7:53 - 13:2]
Clone found (javascript)
 - src/orders.js [1:1 - 12:2] (12 lines, 124 tokens)
   src/reports/orders.js [1:1 - 12:2]
Found 3 clones.

After the clones, the terminal prints one row per format and a total:

Each clone names its two places as file [line:column - line:column] and says how long the shared block is. The percentage is duplication: duplicated lines over all lines, per format and in total. Here it is 13.02 % of 192 lines, and the invoice.js pair appears twice because one inserted line splits it; --max-gap-lines joins the halves.

3. Make it fail

--threshold is the ceiling in percent. When the total duplication is above it, jscpd prints an error after the report and exits with code 1, which fails a pre-commit hook or a CI job.

jscpd . --threshold 1
echo $?

Found 3 clones.
ERROR: jscpd found too many duplicates (13.0%) over threshold (1.0%)
1

Pick a value a little above where the project stands today, so the build stays green until someone adds duplication. To fail only on clones that are new since a known state, use a baseline.

4. Save the settings

jscpd reads .jscpd.json from the directory it runs in (not from the scanned path), then .config/jscpd.json, then the jscpd key of package.json there. Keys are the flags in camelCase; a flag on the command line wins over the file.

{
  "threshold": 3,
  "ignore": ["**/node_modules/**", "**/dist/**"],
  "reporters": ["console", "html"],
  "output": "report"
}

With this file, jscpd . fails above 3 % and writes report/jscpd-report.html next to the console output. jscpd --debug prints the merged settings without scanning, which is the quickest check that the file was picked up.

Where to go next