npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

detecto

v0.3.3

Published

A React library to detect and adapt to user performance issues, such as lag or throttling, ensuring a smoother user experience.

Downloads

492

Readme

Introduction

Detecto is a React library designed to help developers automatically detect when a user's browser is experiencing performance issues such as throttling or lag. When performance issues are detected, the application can adapt to provide a smoother, more lightweight experience for the user.

Modern websites often feature rich animations, high-resolution images, and interactive elements that can be resource-intensive, especially on older or low-powered devices. By using Detecto, you can detect when the user's browsing environment is struggling and adjust your UI dynamically to keep the user experience optimal, even under less-than-ideal conditions.

Key Features

  • Lightweight: Detecto is only ~850B, making it easy to integrate into your project.
  • Frame Rate Monitoring: Track frame rate (FPS) to identify if the user's device is struggling to keep up with animations or other tasks.
  • Long Task Detection: Use the PerformanceObserver API to monitor long-running tasks that could affect responsiveness.
  • Initial Sampling Period: Average frame rates over an initial period (default is 5 seconds) to avoid false positives during the initial page load.
  • Auto-Recovery and Manual Intervention: Choose between automatic recovery with a cooldown (lagRecoveryDelay) or manual intervention to reset the lagging state.
  • Sane defaults and extreme flexibility: Easily adjust detection thresholds and behavior to suit your specific needs or let the library use its defaults.
  • React Hooks: Provides easy integration through a usePerformance hook to access lagging status wherever you need in your application.
  • Fallback Handling: You can optionally define custom behavior when the environment does not support performance detection features.
  • Insightful Logging: Detecto logs key metrics in the development environment at meaningful intervals to help you debug performance issues.

Whether you're building a highly interactive web application or an e-commerce site, Detecto ensures your users enjoy the best experience, regardless of their hardware capabilities or the conditions under which they browse.

Quickstart: Basic Usage

  1. Install the library:

    npm i detecto
  2. Use the PerformanceProvider and usePerformance Hook in your app.

Example (.tsx):

import React from 'react';
import { PerformanceProvider, usePerformance } from 'detecto';

const MyComponent: React.FC = () => {
  const isLagging = usePerformance();

  return (
    <div>
      {isLagging ? (
        <div>Rendering lightweight version...</div>
      ) : (
        <div>Rendering full, animated version...</div>
      )}
    </div>
  );
};

const App: React.FC = () => {
  return (
    <PerformanceProvider>
      {/* Wrap your components with the PerformanceProvider to enable performance monitoring throughout the app or a specific section of it */}
      <MyComponent />
    </PerformanceProvider>
  );
};

export default App;

With the default configuration, the Detecto library will:

  • Detect low frame rates (fpsThreshold of 20).
  • Monitor for long tasks exceeding 50ms.
  • Check performance every second (checkInterval of 1000ms).
  • Average FPS over an initial sampling period of 5 seconds (initialSamplingDuration of 5000ms) to prevent false positives during initial page load.
  • Pause performance monitoring when the page is inactive to prevent misleading metrics.
  • Automatically recover from lagging state after a cooldown (lagRecoveryDelay of 3000ms) or provide a manual reset option.

Browser Requirements

This library uses PerformanceObserver to detect performance issues in the browser. Please note the following:

  • The library requires a modern browser with support for PerformanceObserver. (Basically all browsers since 2015 support it.) If this API is unavailable, throttling detection will be disabled, and a warning will be logged to the console.
  • If you are running in a non-browser environment (e.g., SSR), the hook will log an error and disable itself.

Handling Unsupported Environments

If your target audience includes older browsers, you can:

  • Gracefully degrade features that depend on throttling detection.
  • Use a polyfill where applicable (note that polyfill support for PerformanceObserver may be limited).

Example with Config and Fallback Behavior

import React from "react";
import { usePerformanceStatus, ThrottleDetectionConfig } from "detecto";

const MyComponent: React.FC = () => {
  const config: ThrottleDetectionConfig = {
    fpsThreshold: 20, // Adjust the FPS threshold to determine when lagging is detected
    longTaskThreshold: 50, // Adjust the threshold for long tasks (in milliseconds)
    checkInterval: 1000, // Adjust the interval (in milliseconds) to check for performance issues
    initialSamplingDuration: 5000, // Adjust the initial sampling duration if needed
    lagRecoveryDelay: 3000, // Adjust the delay (in milliseconds) to recover from lag
    autoRecover: false, // Set to false for manual intervention
    onFeatureNotAvailable: () => {
      console.warn("Performance features are not available, running fallback behavior...");
      // Here you could disable some animations, show a fallback UI, etc.
    },
  };

  const { isLagging, resetLagging } = usePerformanceStatus(config);

  return (
    <div>
      {isLagging ? (
        <div>
          Rendering lightweight version...
          <button onClick={resetLagging}>Reset Lagging State</button>
        </div>
      ) : (
        <div>Rendering heavy, animated version...</div>
      )}
    </div>
  );
};

export default MyComponent;

Contributing

We use Commitizen to ensure consistent commit messages. If you want to contribute, please follow the steps outlined in our Contributing Guide and use Commitizen for your commits:

npm run commit

This will guide you through the process of crafting a properly formatted commit message.