treosh/uxm

An utility library for collecting user-centric performance metrics.

Why? • Usage • API • Credits

Features:

• Modular design based on ES modules.
• Small size (2.5kb gzip). It's usually smaller when you use a few features and Tree Shaking.
• Graceful support of latest browser APIs like Performance Paint Timing, Network Information, or Device Memory.
• Fully featured User Timing API v3 support.

Usage

npm install uxm@next

Collect user-centric metrics and send data to your API (1.5Kb):

import { collectMetrics, createApiReporter, getDeviceInfo } from 'uxm'

const report = createApiReporter('/api/collect', { initial: getDeviceInfo() })

collectMetrics(['fcp', 'lcp', 'fid', 'cls'], ({ metricType, value }) => {
  report({ [metricType]: value })
})

At the end of the session (on visibilitychange event), your API receives a POST request (using sendBeacon) with data for core UX metrics and a device information, like:

{
  "fcp": 1409,
  "fid": 64,
  "lcp": 2690,
  "cls": 0.025,
  "url": "https://example.com/",
  "memory": 8,
  "cpus": 2,
  "connection": { "effectiveType": "4g", "rtt": 150, "downlink": 4.25 }
}

Explore examples for building a robust real-user monitoring (RUM) logic. Size of each example is controlled using size-limit.

import { collectFcp, collectFid } from 'uxm'

collectFcp(reportToGoogleAnalytics)
collectFid(reportToGoogleAnalytics)

function reportToGoogleAnalytics(metric) {
  ga('send', 'event', {
    eventCategory: 'Performance Metrics',
    eventAction: 'track',
    [metric.metricType]: metric.value,
  })
}

import { time, timeEndPaint } from 'uxm'

export function App() {
  useTime('render:app')
  return 'Hello from React'
}

function useTime(label) {
  time(label) // render started
  useEffect(() => timeEndPaint(label), []) // render ended, and the browser paint has been procceed.
}

import { observeEntries } from 'uxm'
import { observeHistory } from 'uxm/experimental'

/** @type {{ url: string, cls: number }[]} */
let views = []
let cls = 0

// cummulate `layout-shift` values, with an input

observeEntries('layout-shift', (layoutShiftEntries) => {
  layoutShiftEntries.forEach((e) => {
    if (!e.hadRecentInput) cls += e.value
  })
})

// observe `history` changes,
// and reset `cls` when a route changes

observeHistory((e) => {
  views.push({ url: e.prevUrl, cls })
  cls = 0
})

import { getDeviceInfo, collectLoad, collectFcp, collectLcp, collectFid, collectCls, onVisibilityChange } from 'uxm'

// init `metrics` and get device information

const { connection, url } = getDeviceInfo()
const metrics = { url, effectiveConnectionType: connection.effectiveType }

// collect loading metrics

collectLoad(({ value: load, detail: { domContentLoaded, timeToFirstByte } }) => {
  metrics.timeToFirstByte = timeToFirstByte
  metrics.domContentLoaded = domContentLoaded
  metrics.load = load
})

// collect user-centric metrics

collectFcp(({ value }) => (metrics.firstContentfulPaint = value))
collectLcp(({ value }) => (metrics.largestContentfulPaint = value))
collectFid(({ value }) => (metrics.firstInputDelay = value))
collectCls(({ value }) => (metrics.cumulativeLayoutShift = value))

// all metrics are collected on "visibilitychange" event

onVisibilityChange(() => {
  console.log(metrics)
  //  {
  //    "url": "https://example.com/",
  //    "effectiveConnectionType": "4g",
  //    "timeToFirstByte": 1204,
  //    "domContentLoaded": 1698,
  //    "load": 2508
  //    "firstContentfulPaint": 1646,
  //    "largestContentfulPaint": 3420,
  //    "firstInputDelay": 12,
  //    "cumulativeLayoutShift": 0.12,
  //  }
}, 1)

API

• Metrics
  • collectMetrics(metrics, callback)
  • collectFcp(callback)
  • collectFid(callback)
  • collectLcp(callback, [options])
  • collectCls(callback, [options])
  • collectLoad(callback)
• Performance Observer
  • observeEntries(options, callback)
  • getEntriesByType(entryType)
  • onVisibilityChange(callback)
  • onLoad(callback)
• Reporter
  • createApiReporter(url, [options])
  • getDeviceInfo()
• User-timing
  • mark(markName, [markOptions])
  • measure(markName, [startOrMeasureOptions], [endMarkName])
  • time(label, [startLabel])
  • timeEnd(label, [startLabel])
  • timeEndPaint(label, [startLabel])
  • now()
• Experimental (alpha)
  • collectCid(callback)
  • observeHistory(callback)
  • recordTrace(callback, [options])
  • calcSpeedScore(values, [ranks])

Metrics

Metrics are the core of uxm (uxm is a 3-letter acronym that stands for User eXperience Metrics).

It focuses on metrics, that captures a user experience, instead of measuring technical details, that are easy to manipulate. This metrics are more representetive for a user, and the final purpose of a good frontend is to create a delightful user experience.

Each metric follows the structure:

• metricType <[string]> - a metric acronym, ex: lcp, fid, or cls.
• value <number> - a numeric value of a metric, ex: 1804 for lcp, 4 for fid, or 0.129 for cls.
• detail <object> - an extra detail specific for an each metric, like elementSelector for lcp, event name for fid, or totalEntries for cls.

with an exception for collectLoad (it does not have a 3-letters acronym, and considered a legacy.) Use a per-metric function for more granular control of the callback behavior and saving a bundle size.

This metrics are only available in Chromium-based browsers (Chrome, Edge, Opera).

The best way to understand a metric is to read web.dev/metrics and check the source.

collectMetrics(metrics, callback)

• metrics <array<[string]|object>>
• callback <function>

The method is a shortcut for calling collectFcp, collectFid, collectLcp, and collectCls.

import { collectMetrics } from 'uxm'

const report = createApiReporter('/api/collect')

// pass a metric 3-letter acronym
collectMetrics(['fcp', 'fid'], (metric) => {
  report({ [metric.metricType]: metric.value })
})

// or a metric options using an object and `type`
collectMetrics([{ type: 'lcp', maxTimeout: 1000 }], (metric) => {
  report({ lcp: metric.value })
})

collectFcp(callback)

• callback <function> a callback with FcpMetric:
  • metricType <"fcp">
  • value <number> a time when the user can see anything on the screen – a fast FCP helps reassure the user that something is happening.

Collect First Contentful Paint (FCP) using paint entries.

collectFid(callback)

• callback <function> a callback with FidMetric:
  • metricType <"fid">
  • value <number>
  • detail <object>
    • name <[string]>
    • duration <number>
    • startTime <number>
    • processingStart <number>
    • processingEnd <number>

import { collectFid } from 'uxm'

collectFid((metric) => {
  console.log(metric)
  // { metricType: "fid", value: 1, detail: { duration: 8, startTime: 2568.1, processingStart: 2568.99, processingEnd: 2569.02, name: "mousedown" }
})

collectLcp(callback, [options])

• callback <function> a callback with LcpMetric:
  • metricType <"lcp">
  • value <number> a time when the page's main content has likely loaded – a fast LCP helps reassure the user that the page is useful.
  • detail <object>
    • elementSelector <[string]> CSS selector of an element, that is triggered the most significant paint
    • size <number> size (height x width) of the largest element
• options <object> (Optional)
  • maxTimeout <number> The longest delay between largest-contentful-paint entries to consider the LCP. Defaults to 10000 ms.

Collect Largest Contentful Paint (LCP) using largest-contentful-paint entries. A callback triggers when a user interacts with a page, or after maxTimeout between entries, or on "visibilitychange" event.

import { collectLcp } from 'uxm'

collectLcp((metric) => {
  console.log(metric) // { metricType: "lcp", value: 2450, detail: { size: 8620, elementSelector: "body > h1" } }
})

collectCls(callback, [options])

• callback <function> a callback with ClsMetric:
  • metricType <"cls">
  • value <number>
  • detail <object>
    • totalEntries <number>
    • sessionDuration <number>

import { collectCls } from 'uxm'

collectCls(
  (metric) => {
    console.log(metric) // { metricType: "cls", value: 0.0893, detail: { totalEntries: 2, sessionDuration: 2417 } }
  },
  { maxTimeout: 1000 }
)

collectLoad(callback)

• callback <function> a callback with ClsMetric:
  • metricType <"load">
  • value <number>
  • detail <object>
    • timeToFirstByte <number>
    • domContentLoaded <number>

import { collectLoad } from 'uxm'

collectLoad(({ value: load, detail: { domContentLoaded, timeToFirstByte } }) => {
  console.log({ timeToFirstByte, domContentLoaded, load })
})

Performance Observer

observeEntries(options, callback)

getEntriesByType(entryType)

Reporter

createApiReporter(url, [options])

User Timing

mark(markName, [markOptions])

measure(markName, [startOrMeasureOptions], [endMarkName])

time(label, [startLabel])

timeEnd(label, [startLabel])

timeEndPaint(label, [startLabel])

now()

Device Info

getDeviceInfo()

Experimental (alpha)

collectCid(callback)

observeHistory(callback)

recordTrace(callback, [options])

calcSpeedScore(values, [ranks])

Credits

Made with ❤️ by Treo.