Skip to content

Commit

Permalink
docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@alekseykulikov
alekseykulikov committed Apr 23, 2018
1 parent 0318956 commit 2a6881c
Showing 1 changed file with 35 additions and 32 deletions.
67 changes: 35 additions & 32 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,12 +3,12 @@
</p>

<p align="center">
An utility library for collecting web performance metrics<br />
A utility library for collecting web performance metrics<br />
that affect user experience.
</p>

<p align="center">
<a href="#">Why?</a> • <a href="#example">Usage</a> • <a href="#api">API</a> • <a href="#credits">Credits</a>
<a href="#">Why?</a> • <a href="#usage">Usage</a> • <a href="#api">API</a> • <a href="#credits">Credits</a>
</p>

<br/>
Expand All @@ -24,12 +24,12 @@ UXM is a modular library that allows to combine various functions and collect th
* Collect RUM data.
* Build private version of [Chrome User Experience Report](https://developers.google.com/web/tools/chrome-user-experience-report/).
* Audit the page performance using Puppeteer ([example](./test/index.js)).
* Dynamically evaluate performance of the user's browser and adapt your app.
* Dynamically evaluate the performance of the user's device and adapt the UI.

**Features**:

* Modular design based on ES modules.
* Small size (1kb gzip). It's usually smaller, if you remove unused functions using [Tree Shaking](https://webpack.js.org/guides/tree-shaking/).
* Small size (1kb gzip). It's usually smaller if you use [Tree Shaking](https://webpack.js.org/guides/tree-shaking/).
* Graceful support of latest browser APIs like [Performance Paint Timing](https://developer.mozilla.org/en-US/docs/Web/API/PerformancePaintTiming), [Network Information](https://wicg.github.io/netinfo/), or [Device Memory](https://w3c.github.io/device-memory/).
* Fully featured [User Timing API](https://developer.mozilla.org/en-US/docs/Web/API/User_Timing_API) support.
* Lightweight device type parser.
Expand All @@ -44,12 +44,13 @@ yarn add uxm
npm i -S uxm
```

Import `uxm` and call it in the end of the page loading to collect [CrUX like data](https://developers.google.com/web/tools/chrome-user-experience-report/):
Import `uxm` and call it at the end of the page loading to collect [CrUX-like data](https://developers.google.com/web/tools/chrome-user-experience-report/):

```js
import { uxm } from 'uxm'

uxm().then(metrics => {
console.log(metrics) // ->
{
"deviceType": "desktop",
"effectiveConnectionType": "4g",
Expand All @@ -61,7 +62,7 @@ uxm().then(metrics => {
})
```

Collect just 2 performance metrics associated with `url`:
Or collect 2 performance metrics associated with URL:

```js
import { getUrl, getFirstContentfulPaint, getDomContentLoaded } from 'uxm'
Expand All @@ -73,7 +74,7 @@ const metrics = {
}
```

Analyze current device and connection:
Or analyze current device and connection:

```js
import { getDeviceType, getDeviceMemory, getEffectiveConnectionType } from 'uxm'
Expand All @@ -87,19 +88,21 @@ const device = {

## API

An API is designed in the way that you can combine different functions and collect the data you need.
An API is a set of pure functions with one exception to `uxm`,
which is a meta-function to collect multiple metrics at once.

### uxm(opts = {})

Returns a `Promise` that resolves after `onLoad` event triggered.
Returns a Promise that resolves after `load` event fired.
A default set of metrics is defined by [Chrome User Experience Report](https://developers.google.com/web/tools/chrome-user-experience-report/), but you can customize them using options (`url`, `userAgent`, `deviceMemory`, `userTiming`, `longTasks`, `resources`).

Pass `all` to get the full report:
Or pass `all` to get the full report:

```js
import { uxm } from 'uxm'

uxm({ all: true }).then(metrics => {
console.log(metrics) // ->
{
"deviceType": "phone",
"effectiveConnectionType": "4g",
Expand Down Expand Up @@ -142,7 +145,7 @@ uxm({ all: true }).then(metrics => {

### mark(markName)

Create [User Timing](https://developer.mozilla.org/en-US/docs/Web/API/Performance/mark) mark to mark important loading event. Convenient shortcut for `window.performance.mark`.
Create [User Timing mark](https://developer.mozilla.org/en-US/docs/Web/API/Performance/mark) to mark important loading event. A convenient shortcut for `window.performance.mark`.

```js
import { mark } from 'uxm'
Expand All @@ -156,8 +159,8 @@ mark('page fully loaded')

### measure(measureName, [startMarkName])

Create [User Timing](https://developer.mozilla.org/en-US/docs/Web/API/Performance/mark) measure to evaluate timing between 2 marks.
Convenient shortcut for `window.performance.measure`.
Create [User Timing measure](https://developer.mozilla.org/en-US/docs/Web/API/Performance/mark) to evaluate timing between 2 marks.
A convenient shortcut for `window.performance.measure`.

```js
import { mark, measure } from 'uxm'
Expand All @@ -169,14 +172,14 @@ measure('fonts loaded', 'start load fonts')

### getUserTiming()

Returns an array with collected performance marks/measures. Each item contains:
It returns an array with collected performance marks/measures. Each item contains:

* `type` - "mark" or "measure"
* `name` - unique name
* `startTime` - start time since page load
* `duration` - measure duration

Example response:
Example:

```json
[
Expand All @@ -196,54 +199,54 @@ Example response:

### getFirstContentfulPaint()

Returns the time when first paint which includes text, image (including background images), non-white canvas, or SVG happened.
It returns the time when first paint which includes text, image (including background images), non-white canvas, or SVG happened.
[W3C draft for Paint Timing 1](https://w3c.github.io/paint-timing).

### getFirstPaint()

Similar to `getFirstContentfulPaint` but different when First Paint has no content.
It's similar to `getFirstContentfulPaint` but may contain a different value when First Paint is just background change without content.

### getDomContentLoaded()

Returns the time when [`DOMContentLoaded` event](https://developer.mozilla.org/en-US/docs/Web/Events/DOMContentLoaded) was fired.
It returns the time when [`DOMContentLoaded` event](https://developer.mozilla.org/en-US/docs/Web/Events/DOMContentLoaded) was fired.

### getOnLoad()

Returns the time when [`load` event](https://developer.mozilla.org/en-US/docs/Web/Events/load) was fired.

### getDeviceType()

Returns "phone", "tablet", or "desktop" using lightweight, [heavy-tested]('./test/device.js') the User-Agent parser.
It returns the time when [`load` event](https://developer.mozilla.org/en-US/docs/Web/Events/load) was fired.

### getEffectiveConnectionType()

Returns the effective connection type (“slow-2g”, “2g”, “3g”, “4g”) string as determined by round-trip and bandwidth values.
It returns the effective connection type (“slow-2g”, “2g”, “3g”, or “4g”) string as determined by round-trip and bandwidth values.
[W3C draft for Network Information API](http://wicg.github.io/netinfo/).

### getDeviceType()

It returns the device type ("phone", "tablet", or "desktop") string using the lightweight [heavy-tested]('./test/device.js') user-agent parser.

### getDeviceMemory()

Returns "full" or "lite" string, depends if available memory is bigger than 1 GB.
It returns the device memory ("full" or "lite") string, depends if available memory is bigger than 1 GB.
Learn more about [Device Memory](https://developers.google.com/web/updates/2017/12/device-memory).

### getUrl()

Returns a current page URL. Convenient shortcut for `window.location.href`.
It returns a current page URL. A convenient shortcut for `window.location.href`.

### getUserAgent()

Returns a User-Agent string. Convenient shortcut for `window.navigator.userAgent`.
It returns a User-Agent string. A convenient shortcut for `window.navigator.userAgent`.

### getResources()

Returns an array with performance information for each resource on the page. Each item contains:
It returns an array of performance information for each resource on the page. Each item contains:

* `url` - resource URL
* `type` - one of types: "navigation", "link", "img", "script", "xmlhttprequest", "font"
* `type` - one of resource types ("navigation", "link", "img", "script", "xmlhttprequest", or "font")
* `size` - transferred size in bytes
* `startTime` - when load started
* `duration` - loading time in milliseconds

Example response:
Example:

```json
[
Expand Down Expand Up @@ -281,8 +284,8 @@ Example response:

### getLongTasks()

Returns an array of `{ startTime, duration }` pairs.
Until `buffered` flag supported, you need to add this script to the `<head />` in order to collect all Long Tasks:
It returns an array of `{ startTime, duration }` pairs.
Until `buffered` flag supported, you need to add extra script to the `<head />` to collect all Long Tasks:

```html
<script>
Expand Down

0 comments on commit 2a6881c

Please sign in to comment.