Where Does Nark Store Scan Results? Understanding the .Nark Folder

After your first scan, you might notice a .nark folder appeared somewhere in your project. This article explains what it contains, how Nark decides where to put it, and how to fix the most common placement issue.

What's in the .Nark Folder

Nark stores three types of output locally:

your-repo/
└── .nark/
    ├── scans/          # Numbered scan records (001.json, 002.json, ...)
    │   └── latest -> 003.json
    ├── violations/     # Per-package breakdown, human and machine readable
    │   ├── axios.md
    │   ├── axios.json
    │   └── moment.md
    └── runs/           # Full run artifacts (output.txt, audit.json, HTML report)
        └── 2026042822425-abc1234/
            ├── audit.json
            ├── output.txt
            └── index.html

This is local-first, repo-scoped history. The nark triage and nark show commands read from .nark/violations/ directly, so you can review and act on results without touching the SaaS dashboard.

The .nark folder is automatically added to your .gitignore after every scan. You should never commit it.

How Nark Decides Where to Put .Nark

The location is determined by a single rule:

.nark/ goes in the git root of the directory containing your tsconfig.json.

Specifically, Nark calls findGitRepoRoot(tsconfigPath), which walks up the directory tree from your tsconfig file until it finds a .git folder. That directory becomes projectRoot, and .nark/ is placed at projectRoot/.nark.

npx nark --tsconfig /projects/my-api/tsconfig.json
                              ↓
                   starts here, walks up...
                              ↓
                   finds /projects/my-api/.git
                              ↓
                   .nark/ → /projects/my-api/.nark/  ✓

The Most Common Problem: .Nark Appears in the Wrong Folder

If you run npx nark without --tsconfig from a directory that isn't your project root, the .nark folder will appear in the wrong place.

What happens:

1. The default --tsconfig is ./tsconfig.json — relative to your current working directory (CWD), not the repo you want to scan.
2. If that file doesn't exist, Nark generates a synthetic tsconfig.json at {CWD}/.nark/tsconfig.json.
3. Now findGitRepoRoot walks up from inside your CWD's .nark folder — not from your target repo.
4. .nark/ ends up in the git root of your CWD, not the repo you scanned.

Example:

# You're in a tools directory, want to scan a different repo
cd /workspace/nark-tools
npx nark   # No --tsconfig flag!

# Nark looks for ./tsconfig.json — doesn't exist
# Generates synthetic tsconfig at /workspace/nark-tools/.nark/tsconfig.json
# Walks up from there, finds /workspace/.git
# Output goes to /workspace/.nark/  ← wrong!

The Fix: Always Use --tsconfig With an Absolute Path

When scanning a repo that isn't your current directory, pass the full absolute path:

# Always works, regardless of where you run it from
npx nark --tsconfig /absolute/path/to/target-repo/tsconfig.json

Or cd into the repo first:

cd /path/to/target-repo
npx nark

A relative path also works, as long as the file actually exists at that path:

# Only safe if this resolves to a real file in the target repo
npx nark --tsconfig ../../target-repo/tsconfig.json

The key rule: the tsconfig file must exist. If Nark can't find it, it generates one in your CWD and the output location goes wrong.

Verifying the Output Location Before Scanning

You can check where Nark will write output by looking at where your tsconfig resolves to:

# Check what tsconfig Nark will use
ls $(pwd)/tsconfig.json

# Or pass explicitly and verify it exists
ls /path/to/repo/tsconfig.json && npx nark --tsconfig /path/to/repo/tsconfig.json

Using .Nark/config.yaml to Set a Default tsconfig

If you always scan the same project from a tools directory, add a .nark/config.yaml to your CWD:

# .nark/config.yaml in your working directory
tsconfig: /absolute/path/to/target-repo/tsconfig.json

Nark reads this automatically, so you can just run npx nark without flags.

Summary

The .nark folder is designed to live in your scanned repo, accumulate scan history over time, and stay gitignored. When you point Nark at the right tsconfig, it works exactly that way.