Why Adopt Nark for Your Engineering Team

You already run ESLint and maybe Semgrep. Your team writes tests. You do code review. And yet, every quarter, someone gets paged because an axios.get() call does not have a try-catch, or a Prisma create() throws P2002 on a duplicate record and returns a 500 to the user. These bugs pass every check you have because no existing tool in your pipeline knows what npm packages throw at runtime. Nark does. Adding it to CI takes 5 minutes and closes a gap that code review, linting, and tests cannot.

Quick Answer: Nark adds a new quality gate to your CI pipeline: runtime error handling verification for axios, prisma, stripe, redis, and 160+ npm packages. It catches the bugs that ESLint, Semgrep, and code review miss. Setup is one line in your CI config. The ROI is immediate: every violation Nark finds is a production incident that has not happened yet. npx nark --tsconfig ./tsconfig.json

The Problem You Are Solving

Your team has code quality tooling. Here is what each tool catches and what falls through:

The gap is specific: nobody checks whether your code handles the errors that npm packages actually throw. Not ESLint, not Semgrep, not TypeScript, not your test suite, and not your code reviewers (because they would need to memorize the error behavior of every dependency).

Nark fills this gap. It scans your TypeScript AST against Nark Profiles that encode what each package throws, when it throws it, and what correct handling looks like.

What Adoption Looks Like

Day 1: Run the First Scan (5 minutes)

npx nark --tsconfig ./tsconfig.json

This produces a list of violations. A typical project with 20-50 dependencies has 5-15 violations on the first scan. Each violation is a specific function call that is missing error handling:

ERROR  axios         axios.get() called without try-catch
       src/lib/api-client.ts:42  in fetchUser()

ERROR  @prisma/client  prisma.user.create() without P2002 handling
       src/routes/signup.ts:23  in createAccount()

ERROR  stripe        stripe.charges.create() without StripeCardError handling
       src/billing/charge.ts:8  in processPayment()

5 violations found across 3 packages

Share this output with your team. The reaction is immediate recognition: "I know exactly which incident that would have caught."

Week 1: Add to CI (5 minutes)

# .github/workflows/ci.yml
- name: Nark — runtime error handling
  run: npx nark --tsconfig tsconfig.json

Nark now runs on every PR. New violations fail the build. Existing violations are the baseline.

Week 1-2: Fix the Baseline

Create tickets for each existing violation. Assign them to the engineers who own those code paths. Each fix is a try-catch that takes 5-15 minutes.

This is a good onboarding task for new team members. It teaches them the codebase and the error handling patterns your team uses.

Ongoing: Zero New Violations

Once the baseline is clean, the CI check ensures no new unhandled errors ship. When an engineer writes await axios.get(...) without a try-catch, Nark fails the PR before code review even starts. The reviewer does not need to catch it. The tool did.

The Business Case

Reduced Incident Frequency

Each Nark violation is a potential production incident. A project with 10 violations at the start has 10 latent bugs that will fire when conditions are right (network timeout, duplicate record, API rate limit, connection drop). Fixing them eliminates those incidents before they happen.

A single prevented production incident saves $5,000-$25,000 in engineering time, customer support, and lost productivity. Preventing one incident per quarter saves $20,000-$100,000 per year.

Faster Code Review

Code reviewers currently need to mentally verify error handling on every API call. This is slow, inconsistent, and depends on the reviewer knowing every package's error behavior. When Nark handles this check automatically, reviewers can focus on logic, architecture, and design. Reviews get faster and more consistent.

Better On-Call Experience

Engineers who are on-call for services with comprehensive error handling get paged less. The 2am pages for "axios call crashed the payments endpoint" stop happening. This directly improves retention. On-call fatigue is a top reason senior engineers leave.

Consistent Standards Across the Team

Every team has engineers who are meticulous about error handling and engineers who are not. Nark enforces a consistent standard regardless of who wrote the code. The junior engineer's PR gets the same error handling check as the senior engineer's.

Audit and Compliance Evidence

For teams operating under SOC 2 or similar frameworks, Nark's CI output is evidence that "all error paths are verified before deployment." This is a concrete control that auditors understand. It is more compelling than "we do code review" because it is automated and deterministic.

How to Introduce It to Your Team

Step 1: Run It Yourself First

Before proposing it to the team, run Nark on your project and read the results. Understand what it finds. Verify that the violations are real (they will be). Note which ones you recognize from past incidents.

Step 2: Show, Don't Tell

Do not send a Slack message saying "I found a new linting tool." Instead, share the scan output in your team channel:

"Ran a new scanner on our repo. It found 8 places where we call npm packages without handling the errors they throw. Here are the top 3 — does anyone recognize these patterns from past incidents?"

Let the output speak for itself. Engineers trust tools that find real bugs in their own code.

Step 3: Start as Non-Blocking

Add Nark to CI as a non-blocking check initially:

- name: Nark — runtime error handling (non-blocking)
  run: npx nark --tsconfig tsconfig.json || true

This lets the team see violations on their PRs without blocking merges. After 1-2 weeks, when the team has seen the value, switch to blocking.

Step 4: Fix the Baseline Together

Create a tracking issue with all existing violations. Break it into small PRs (one per package or one per file). Assign them across the team. This works well as a team sprint goal: "zero Nark violations by end of sprint."

Step 5: Make It Blocking

Once the baseline is clean, flip the CI check to blocking:

- name: Nark — runtime error handling
  run: npx nark --tsconfig tsconfig.json

From this point forward, no new unhandled errors ship. The quality gate is in place.

Objections You Will Hear (and How to Respond)

"We already have ESLint."

ESLint catches code style and floating promises. It does not know what axios.get() throws. It does not know that prisma.user.create() can throw P2002. These are different categories of bugs. ESLint and Nark do not overlap.

"We can catch these in code review."

You can, if the reviewer happens to know the error behavior of the specific package being called, and they happen to notice the missing try-catch, and they are not reviewing 400 lines of changes at 4pm on a Friday. Nark catches it every time, on every PR, with zero reviewer fatigue.

"We have monitoring. We'll catch it in production."

Monitoring reduces detection time. It does not prevent the incident. The customer already saw the 500 error. The on-call engineer already got paged. The fix still takes hours. Prevention is 400x cheaper than response.

"We don't have time to add another tool."

Adding Nark to CI is one line in your workflow file. Fixing violations takes 5-15 minutes each. The time investment to set up Nark is less than the time your team spent on the last production incident caused by a missing try-catch.

"What if it has false positives?"

Nark's checks are binary: either your code handles the error or it does not. There is no heuristic or probability. If Nark says axios.get() is called without a try-catch, it is. You can suppress specific violations with inline comments if the call is intentionally unhandled.

Metrics to Track After Adoption

Leading Indicators (Week 1-4)

• Violations fixed per week. Track the baseline going to zero.
• PRs blocked by Nark. Each one is a bug that would have shipped.
• Time from Nark adoption to zero baseline. This is a team velocity signal.

Lagging Indicators (Month 2+)

• Production incident frequency. Compare the quarter before and after adoption. Focus on incidents caused by unhandled npm package errors specifically.
• Mean time to resolve (MTTR). Should decrease because the remaining incidents are less common and better understood.
• On-call page frequency. Fewer pages for "endpoint returning 500 because [package] threw an unhandled error."

What to Report to Leadership

"Since adopting Nark 3 months ago, we've caught 23 unhandled error cases in PRs before they shipped. Based on our historical incident rate, we estimate this prevented 2-3 production incidents worth $10,000-$30,000 each in engineering time and customer impact. The tool took 5 minutes to set up and runs automatically on every PR."

This is the kind of concrete, measurable improvement that makes engineering leadership reports compelling.

Who Benefits Most

The person who introduces Nark to the team gets credit for reducing incidents, improving developer experience, and strengthening the CI pipeline. It is a visible, measurable improvement with a clear before/after.

Quick Start

1. Scan your project

npx nark --tsconfig ./tsconfig.json

2. Add to CI

- name: Nark — runtime error handling
  run: npx nark --tsconfig tsconfig.json

3. Fix the baseline

Each violation is a 5-15 minute fix. Assign across the team.

4. Ship with confidence

No new unhandled errors pass CI. The quality gate is in place.

Try It Now

npx nark --tsconfig ./tsconfig.json

Nark checks 160+ packages — including axios, prisma, stripe, and redis — for correct error handling. Run the scan, share the results with your team, and add it to CI. Five minutes of setup. Measurable reduction in production incidents. The kind of improvement that shows up in quarterly reviews.