@plasius/nfr

Overview

@plasius/nfr provides Non-Functional Requirement assistance, exposing platform agnostic Analytics, Performance Tracking and more.

Installation

npm install @plasius/nfr

Usage Example

Analytics & Performance

import React from "react";
import { withInteractionTracking, trackPerf, initPerformanceTracking } from "@plasius/nfr";

// Example: wrap a component with interaction tracking
const Button = React.forwardRef<HTMLButtonElement, React.ComponentProps<"button">>(
  (props, ref) => (
    <button ref={ref} {...props}>
      Click me
    </button>
  )
);
const TrackedButton = withInteractionTracking(Button, { origin: "docs" });

// Example: initialize performance tracking
const teardown = initPerformanceTracking({
  track: trackPerf,                    // re-use our analytics pipeline
  resourceSampleRate: 0.25,            // optional (default 0.25; set 0 to disable)
  resourceFilter: (r) => r.initiatorType !== "img", // optional
  includeNetworkInfo: true,            // optional (default true)
  includeMemorySnapshot: false,        // optional (default false)
});

// Example: manual performance event (use a supported PerfCategory)
trackPerf({
  category: "resource",
  name: "user-action",
  ts: Date.now(),
  details: { action: "something-happened" },
});

Notes:

• Web Vitals are loaded via optional web-vitals; if it isn’t installed, those metrics are skipped.
• initPerformanceTracking safely no-ops in SSR/non-DOM environments.

Testing

Run npm test -- --coverage to execute the Vitest suite (jsdom) and generate coverage reports in coverage/ (currently ~95% line coverage). The harness automatically preloads a tiny shim to provide vm.constants.DONT_CONTEXTIFY on Node 20 so jsdom can start safely.

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

• Code of Conduct
• Contributor License Agreement

License

This project is licensed under the terms of the Apache 2.0 license.