@yqg/assets-retry

English | 简体中文

Auto Assets Retry

A tiny non-intrusive library to retry your assets (scripts, stylesheets, images) when they failed to load, only 3 KB gzipped, even works with dynamic import!

Demo URL

Table of Contents

• Installation
  • Install with npm
  • Use inline script directly
• Usage
• Config
• FAQ
• Browser Support
• Acknowledgement

Installation

Install with npm

$ npm install assets-retry --save

Then, inject the library at the beginning of the page with proper webpack configurations. See example

Use inline script directly

If you don't want to spend your time fiddling around with webpack configurations, you can inline the minified file with a script tag, and place it at the beginning of the page.

Usage

All you have to provide is the domain parameter, which are the domains to retry when assets failed to load.

// information of assets
var assetsRetryStatistics = window.assetsRetry({
    // domain list, only resources in the domain list will be retried.
    domain: ['your.first.domain', 'your.second.domain/namespace'],
    // maximum retry count for each asset, default is 3
    maxRetryCount: 3,
    // onRetry hook is how you can customize retry logic with, default is x => x
    onRetry: function(currentUrl, originalUrl, statistics) {
        return currentUrl
    },
    // for a given resource (except background-images in css),
    // either onSuccess or onFail will be eventually called to
    // indicate whether the resource has been successfully loaded
    onSuccess: function(currentUrl) {
        console.log(currentUrl, assetsRetryStatistics[currentUrl])
    },
    onFail: function(currentUrl) {
        console.log(currentUrl, assetsRetryStatistics[currentUrl])
    }
})

When the initialization is finished, following content gains the power of retrying automatically.

• All <script> tag in html
• All <link rel="stylesheet"> tag in html (properly configured)
• All <img> tag in html
• All dynamic script element created with document.createElement, such as dynamic import.
• All background-image in css

Config

The assetsRetry function takes an AssetsRetryOptions, which is defined as follows:

interface AssetsRetryOptions {
    maxRetryCount: number
    onRetry: RetryFunction
    onSuccess: SuccessFunction
    onFail: FailFunction
    domain: Domain
}
type RetryFunction = (
    currentUrl: string,
    originalUrl: string,
    retryCollector: null | RetryStatistics
) => string | null
interface RetryStatistics {
    retryTimes: number
    succeeded: string[]
    failed: string[]
}
type SuccessFunction = (currentUrl: string) => void
type FailFunction = (currentUrl: string) => void
type Domain = string[] | { [x: string]: string }

• domain: domain list, can be array or object type
  • array type: assets will be retried from each domain in sequence, until it's loaded successfully or exceed maximum retry times.
  • object type: { 'a.cdn': 'b.cdn', 'c.cdn': 'd.cdn' } means failed assets from a.cdn should be retried from b.cdn, failed assets from c.cdn should be retried from d.cdn
• maxRetryCount: maximum retry count for each asset, default is 3
• onRetry: hook function which was called before trying to load any assets
  • the function takes 3 parameters:
    • currentUrl: next url to try
    • originalUrl: last failed url
    • retryCollector: information collector for current asset, if the asset was from url() function defined in your stylesheets, it will be null. When it's not null, it's an object with following properties:
      • retryTimes: current retry times (starts from 1)
      • failed: failed assets list(may be duplicated when retrying from the same domain multiple times)
      • succeeded: succeeded assets list
  • the function must return a String or null:
    • when null was returned, current retry will be terminated.
    • when string was returned, current retry url will be the return value.
• onSuccess: hook function which was called when asset has loaded
  • currentUrl: return the asset name which you can use to get statistics from information collector
• onFail: hook function which was called when asset failed to load
  • currentUrl: return the asset name which you can use to get statistics from information collector

FAQ

• Q: Stylesheets or background images are not retried from backup domain, why?

  A: Due to security policies of browsers, access to cssRules is not allowed for cross origin stylesheets by default. To fix this:

  • Add crossorigin="anonymous" attribute on link element for cross origin stylesheets.
  • Make sure that Access-Control-Allow-Origin HTTP Header is correct.

Browser Support

47+ ✔	15+ ✔	32+ ✔	10+ ✔	34+ ✔	10+ ✔	10+ ✔	4.4+ ✔

NPM scripts

• npm t: Run test suite
• npm start: Run npm run build in watch mode
• npm run test:watch: Run test suite in interactive watch mode
• npm run test:prod: Run linting and generate coverage
• npm run build: Generate bundles and typings, create docs
• npm run lint: Lints code
• npm run commit: Commit using conventional commit style (husky will tell you to use it if you haven't :wink:)

Acknowledgement

• The example projects are based on amazing RealWorld demo apps.
• Cross browser testing are based on the rather excellent BrowserStack UI testing technology.