@nzila/sdk

Send test runs to Nzila and trace live errors on the same feature names as your Vitest suites.

Silent by design: webhook and runtime delivery never throw, never log to the console, and skip work when URL/key are missing — your app and CI are unaffected if Nzila is down or misconfigured.

Install

npm install @nzila/sdk
# Vitest projects also need vitest as a peer

CommonJS ("type": "commonjs" or jest.config.cjs)

The package is published as dual ESM + CJS:

• import … from "@nzila/sdk" → ESM (dist/)
• require("@nzila/sdk") → CJS (dist/cjs/, via exports.require)
• Jest: require("@nzila/sdk/jest") uses jest.cjs (sync, no dynamic import())

All subpaths (/vitest, /jest, /mocha, /runtime, /react) expose both import and require in package.json exports.

TypeScript

Subpaths such as @nzila/sdk/vitest need moduleResolution set to bundler, node16, or nodenext (recommended for Vitest/Vite repos). If you still use legacy "node" resolution, upgrade to one of those options in tsconfig.json:

{
  "compilerOptions": {
    "moduleResolution": "bundler"
  }
}

@nzila/[email protected]+ also ships root .d.ts shims and typesVersions for broader editor support.

Vitest reporter API

NzilaVitestReporter implements Vitest’s Reporter interface and sends the webhook in onTestRunEnd (after all modules finish). Optional hooks like onTestCaseResult are not required.

Vitest: tests hang or never start?

Use the tuple from nzilaVitestReporter() — do not put new NzilaVitestReporter() in vitest.config.ts. Worker pools cannot serialize class instances.

reporters: ["default", nzilaVitestReporter({ webhookUrl, apiKey, appName })],

Equivalent: reporters: ["default", ["@nzila/sdk/vitest", { … }]].

Reporters not sending?

1. Set NZILA_WEBHOOK_URL, NZILA_API_KEY, and NZILA_APP_NAME (must match the project app name in the dashboard), or pass them in the reporter constructor.
2. Run with NZILA_DEBUG=1 to see skip/send messages on stderr (reporters are silent by default).
3. Vitest 3+ uses onTestRunEnd — use @nzila/[email protected]+.
4. Jest with jest.config.cjs: use reporters: [["@nzila/sdk/jest", { … }]] and const { reporterOptionsFromNzilaConfig } = require("@nzila/sdk") when needed.

CLI (onboarding)

npx @nzila/sdk opens the Nzila dashboard and prints setup commands. No separate CLI package.

npx @nzila/sdk              # open app + help
npx @nzila/sdk login
npx @nzila/sdk link --api-key <key> --project-id <uuid>
npx @nzila/sdk doctor

Also available as npx nzila after install. Override platform with NZILA_APP_URL or --endpoint.

After you sign in on nzila-kappa.vercel.app, the dashboard runs a first-visit tour per section (localized). Use Guide in the header to replay.

Exports

| Path | Purpose | |------|---------| | @nzila/sdk | Webhook delivery, reporters, runtime tracing | | @nzila/sdk/vitest | Vitest reporter | | @nzila/sdk/jest | Jest reporter | | @nzila/sdk/mocha | Mocha reporter | | @nzila/sdk/react | NzilaProvider, useNzilaFeature, error boundary | | @nzila/sdk/runtime | initNzilaRuntime, traceNzilaFeature |

Quick start

Tests (CI):

import nzilaConfig from "./nzila.config";
import { nzilaVitestReporter } from "@nzila/sdk/vitest";
import { reporterOptionsFromNzilaConfig } from "@nzila/sdk";

export default defineConfig({
  test: {
    reporters: [
      "default",
      nzilaVitestReporter(reporterOptionsFromNzilaConfig(nzilaConfig)),
    ],
  },
});

nzila.config.ts (from npx @nzila/sdk link --api-key … --project-id <uuid> --app-name <app>):

export default {
  apiKey: "nzl_…",
  projectId: "00000000-0000-0000-0000-000000000000",
  appName: "my-app",
  endpoint: "https://nzila-kappa.vercel.app",
  framework: "vitest",
} as const;

Or set env vars: NZILA_API_KEY, NZILA_PROJECT_ID, NZILA_APP_NAME, NZILA_WEBHOOK_URL.

React (runtime):

"use client";
import { NzilaProvider, useNzilaFeature } from "@nzila/sdk/react";

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <NzilaProvider
      signalsUrl={process.env.NEXT_PUBLIC_NZILA_SIGNALS_URL!}
      apiKey={process.env.NEXT_PUBLIC_NZILA_API_KEY!}
    >
      {children}
    </NzilaProvider>
  );
}

function Checkout() {
  const nzila = useNzilaFeature("Checkout");
  // nzila.captureError(err) in catch; nzila.runApi("label", () => fetch(...))
}

Backend:

import { initNzilaRuntime, traceNzilaFeature } from "@nzila/sdk";

const nzila = traceNzilaFeature("Checkout");
await nzila.runApi("charge", () => charge());

Examples (included in this package)

After install, open node_modules/@nzila/sdk/examples/:

• INDEX.md — map of all samples
• COMPLEX-USAGE.md — every feature (Vitest, runtime, mapFeature, webhooks)
• RUNTIME-TRACE.md — React + backend live tracing
• TRACING-FAILURES.md — tests → dashboard
• Config: vitest.config.example.ts, jest.config.example.cjs, mocharc.nzila.example.cjs
• Code: backend/, frontend/, complex/, react/checkout-feature.example.tsx

All example imports use @nzila/sdk (same as your app).