Speed Kit 1.12.3

Baqend Speed Kit accelerates your existing website by rerouting the requests through Baqend's caching infrastructure. Thereby you gain a remarkable boost of performance to your website.

Download

Use the following links to download version 1.12.3 of Speed Kit.

  • Service Worker

    The Service Worker needs to be served from your website under the root directory, i.e. https://www.example.org/sw.js.

    Download sw.js
  • Snippet

    Use the snippet in your site to enable and configure Speed Kit. It needs to be included into your page.

    Download snippet.js
  • Dynamic Fetcher

    Use the snippet in your site to handle Dynamic Blocks. It needs to be included into your page when you use Dynamic Blocks e.g. for personalized or segmented content.

    Download dynamic-fetcher.js

Configuration Examples

After you have downloaded and installed Speed Kit, you have to configure the snippet with the speedKit variable. Take the following example:

var speedKit = {
  appName: 'my-speed-kit-app', // Your app on Baqend
  whitelist: [
    // Only apply Speed Kit on URLs whose pathname starts with "/assets"
    { pathname: '/assets' }
  ],
  blacklist: [
    // Only blacklist URLs which match the regular expression "/content/" and are HTML documents
    { url: /content/, contentType: ['document'] }
  ]
};
// ... embed the snippet here ...

Then, you can include the snippet which takes the speedKit variable and enables the ServiceWorker.

You can find all options for the speedKit variable in the SpeedKitConfig interface.

If you use Dynamic Blocks (e.g. for personalized or segmented content), you need to include the Dynamic Fetcher into your HTML above your Speed Kit config. You can configure the Dynamic Fetcher with the dynamicBlockConfig variable. Take the following example:

var dynamicBlockConfig = {
  blockSelector: '.dynamic-block',
  tagAttribute: 'data-block-id',
  statusClass: 'speed-kit',
  forceFetch: true,
};
// ... embed the Dynamic Fetcher here ...

Then, you can include the Dynamic Fetcher which takes the dynamicBlockConfig variable.

You can find all options for the dynamicBlockConfig variable in the DynamicBlockConfig interface.

SpeedKitConfig

Add the following properties to your speedKit variable.

appName

required The name of your Baqend app.

Allowed values: string

appDomain

advanced The domain to connect to your Baqend app.

Allowed values: string

Example value: speed-kit.example.org

disabled

Whether to disable the service worker on this page.

Allowed values: boolean

Default value: false

enabledSites (since 1.1.1)

Rules to identify html sites on which Speed Kit should be enabled. No rules means Speed Kit is enabled on every site.

Allowed values: SpeedKitRule[]

Default value: []

Example value: [{ url: /^www\.baqend\.com\/speedkit\//}]

whitelist

Some rules for requests which should be intercepted (empty to match every request).

Allowed values: SpeedKitRule[]

Default value: []

Example value: [{ pathname: "/assets" }]

blacklist

Some rules for requests which should not be intercepted.

Allowed values: SpeedKitRule[]

Default value: []

Example value: [{ url: /robots\.txt$/, contentType: ["document"] }]

delayed (since 1.10.0)

Some rules for requests which should be intercepted, but delayed, to improve the critical rendering path of your website.

Allowed values: SpeedKitRule[]

Default value: []

Example value: [{ url: 'www.googletagmanager.com/gtm.js' }]
Speed Kit will delay the Google Tag Manager request to speed up all render-critical requests.

userAgentDetection

Enables the user agent detection which distinguishes requests between mobile and desktop.

Allowed values: boolean

Default value: false

stripQueryParams (since 1.10.0)

A set of rules to match against query params which should be stripped from requested URLs before they are fetched.

Allowed values: Condition

Default value: null

Example value: ['analytics', 'gclid']
Speed Kit will remove “analytics” and “gclid” query parameters before issuing and caching the request.

sw

advanced Location of the service worker.

Allowed values: string

Default value: "/sw.js"

scope

advanced The Scope under which Speed Kit will be active.

Allowed values: string

Default value: "/"

maxStaleness (deprecated)

advanced The refresh interval of the Bloom filter in milliseconds, i.e. this interval decides the maximum staleness of assets on your site.

Deprecated: Use SpeedKitConfig.refreshInterval (in seconds) instead.

Allowed values: number

Default value: 300000

refreshInterval

advanced The refresh interval of the Bloom filter in seconds, i.e. the interval to refresh metadata on the staleness of cache entries. This interval effectively decides the maximum staleness of assets on your site.

Allowed values: number

Default value: 300

staleWhileRevalidate

advanced The user session length in seconds in which the Bloom filter is used to decide the staleness of HTML cache entries while being refreshed in the background. This setting increases cache hits for HTML files drastically and should represent the length your users' sessions.

Allowed values: number

Default value: 1800 (30 min)

reconnectInterval (since 1.1.0)

advanced The interval in which to try to reconnect to the disconnected Baqend app in milliseconds.

Allowed values: number

Default value: 60000

disableCache

advanced Disables using the ServiceWorker cache.

Allowed values: boolean

Default value: false

preloadBloomFilter

advanced Load the Bloom filter when activating Speed Kit.

Allowed values: boolean

Default value: true

fetchOriginInterval (since 1.2.0)

An interval in which Speed Kit will call the original document, e.g., to receive its cookies.

In order to update your client's cookies or renew the user session, Speed Kit is able to tee document requests so user-specific Set-Cookie headers are asynchronously fetched from your originating backend and applied in the browser.

The following values are allowed:

Value Description
−1 Do not tee the request (costs least bandwidth of your origin) – default.
0 Always tee the request (costs most bandwidth of your origin).
X > 0 Tee the request at most every X seconds (saves bandwidth of your origin).

Allowed values: number

Default value: -1

Example value: 60
The request will only be teed against your origin backend when the last call has not been made more than one minute ago.

image (since 1.5.0)

Applies optimizations to images served by Speed Kit.

You can use an array of ImageRules to tell Speed Kit how images should be handled. The config looks for example like this:

var speedKit = {
  // ... other options ...
  image: [
    {
      // apply options to images under "/images/teasers/"
      rules: [{ "pathname": "/images/teasers/" }],
      options: {
        quality: 95,
        downscale: true,
      },
    }, {
      // apply options to images under "/images/photos/"
      rules: [{ "pathname": "/images/photos/" }],
      options: {
        quality: 75,
        webp: false,
      },
    }, {
      // default options
      options: {
        quality: 65,
        webp: true,
        downscale: false,
      },
    },
  ],
  // ... other options ...
};
All images which are not matched by a rule will be applied with the default options (see ImageOptions).

You can also just pass an object of ImageOptions to this option if you want to override the defaults globally:

var speedKit = {
  // ... other options ...
  image: {
    quality: 95, // change default quality from 85% to 95%
    webp: false, // disable WebP support which is enabled by default
  },
  // ... other options ...
};

Allowed values: ImageOptions | ImageRule[]

Example value: [{ rules: [{ "pathname": "/assets/img/" }], options: { quality: 65, downscale: true } }]
In this example, Speed Kit will compress all images under the "/assets/img/" path with a quality of 65% and limit its size to the user's screen. All other images will not be manipulated at all.

criticalResources (since 1.11.0)

Rules to identify critical resources of an HTML document.

You can use an array of ResourceRules to tell Speed Kit which are the critical resources of specific pages that should be handled with higher priority.

The config looks for example like this:

var speedKit = {
  // ... other options ...
  criticalResources: [{
    // apply specific critical resources for different pages
    enabledOn: [{ pathname: ["index.html"] }],
    resources: ["/assets/picture.jpg"],
  }, {
    // global critical resources
    resources: ["/assets/logo.png"],
  }],
  // ... other options ...
};

You can also just pass an array of strings to globally define critical resources for all pages of your site:

var speedKit = {
  // ... other options ...
  criticalResources: ["/assets/logo.png"],
  // ... other options ...
};

Allowed values: (string | ResourceRule)[]

Default value: []

Example value: [{ enabledOn: [{ pathname: ["index.html"] }], resources: ["/assets/logo.png"] }]

SpeedKitRule

Use rules in your whitelist and blacklist to describe resource patterns.

url

A condition to test against the whole URL, e.g. “www.baqend.com/some/path#and-fragment-part”.

Allowed values: Condition

Example value: /^www\.baqend\.com\//

host

A condition to test against the host, e.g. “www.baqend.com”, “www.baqend.com:8443”.

Allowed values: Condition

Example value: /\.com$/

pathname

A condition to test against the path name, e.g. “/some/path/here”.

Allowed values: Condition

Example value: /\/robots\.txt$/

mobile (since 1.5.0)

Only fulfills this rule if sent from a mobile device.

Allowed values: true

desktop (since 1.5.0)

Only fulfills this rule if sent from desktop.

Allowed values: true

tablet (since 1.5.0)

Only fulfills this rule if sent from a tablet.

Allowed values: true

tv (since 1.5.0)

Only fulfills this rule if sent from a TV.

Allowed values: true

A condition tested against cookie names.

Use the cookie rule to test if a cookie with a given name exists. The Condition that you pass to this attribute will be matched against all available cookie names and this rule is fulfilled, when there exists at least one cookie with a name which matches that Condition.

Allowed values: Condition

Example value: /^PHPSESSID|JSESSID$/
This rule is fulfilled when there exists a cookie with the name PHPSESSID or JSESSID.

contentType

An array of content types to use.

Allowed values: ContentType[]

Example value: ["document", "style", "script", "image"]

DynamicBlockConfig

Add the following properties to your dynamicBlockConfig variable.

blockSelector

The query selector to identify dynamic blocks.

You can use CSS classes or any other query selector.

Allowed values: string

Default value: ".speed-kit-dynamic"

tagAttribute

The tag attribute to get a unique block id from. You can also supply a custom function to generate an id from the dynamic block that is given as an input parameter.

Each Dynamic Block needs a unique ID in order to be replaced with the right content. This tag attribute is where the Dynamic Fetcher can find this ID. You can use data attribute or just element IDs for example. If a dynamic block has no such attributes and you cannot add them, you can use a custom function to generate a unique id from the dynamic block as an input value.

Allowed values: string | (elem: HTMLElement) ⇒ string

Default value: "data-speed-kit-id"

statusClass

The prefix of the status HTML classes, which will be attached to the HTML tag.

For example, you can use these classes to hide Dynamic Blocks before their content has been replaced.

The classes that will be attached to the HTML element are:

  • <statusClass>-loading will be appended before the Dynamic Blocks are replaced for the actual content.
  • <statusClass>-loaded will be appended after the Dynamic Blocks have been replaced.

Allowed values: string

Default value: "speed-kit-dynamic"

forceFetch

advanced Forces to always fetch the origin's version of the HTML.

Option to check for Dynamic Blocks in the HTML before requesting the dynamic data. If false, the origin's HTML will only be fetched when Dynamic Blocks are detected. If true, the origin's HTML will be fetched right away (faster).

Allowed values: boolean

Default value: true

customMergeFunction

advanced required Defines a custom function to merge a dynamic block loaded from the origin with its cached counterpart. The default merge function simply swaps the local for the remote block.

Allowed values: (localBlock: HTMLElement, remoteBlock: HTMLElement) ⇒ void

Default value: (localBlock, remoteBlock) => {localBlock.outerHTML = remoteBlock.outerHTML;}

ImageOptions

These options can be applied on images. See the image option for more information.

quality (since 1.5.0)

The quality in which images should be returned by Speed Kit.

We are using a lossy compression to speed up the delivery of your images. Under normal circumstances, the default quality of 85% will still result in good looking images.

If you pass a number between 0 and 100 to the option, it will be interpreted as a percentage representing the quality. All images handled by Speed Kit will be delivered with this quality. A value of 100 means no loss in quality.

You can disable the feature completely by setting the option to false.

Allowed values: false | number

Default value: 85

downscale (since 1.5.0)

Downscales image dimensions to the user's screen.

This option helps to reduce image file sizes, especially for mobile. If your website delivers images that are larger than the user's display requires, they are automatically scaled down to the screen.

Allowed values: boolean

Default value: true

screenSizeFactor (since 1.8.0)

Multiplies screen dimensions with this factor to deliver smaller images.

Because modern mobile screens are massive, this options gives you the opportunity to multiply the screen size with a factor between 0 and 1. This way Speed Kit can request much smaller images and safe bandwidth. Note: The downscale options must be enabled (default) for this option to take effect.

Allowed values: number

Default value: 1

maxWidth (since 1.8.0)

Downscales images to this maximum width.

If you happen to know the maximum width of an image, you can use this option to tell Speed Kit how much to downscale. This can help to reduce file sizes significantly. If this option is set to false (default), the max width is inferred from the devices screen size. Note: The downscale options must be enabled (default) for this option to take effect.

Allowed values: number | false

Default value: false

maxHeight (since 1.8.0)

Downscales images to this maximum height.

If you happen to know the maximum height of an image, you can use this option to tell Speed Kit how much to downscale. This can help to reduce file sizes significantly. If this option is set to false (default), the max width is inferred from the devices screen size. Note: The downscale options must be enabled (default) for this option to take effect.

Allowed values: number | false

Default value: false

webp (since 1.5.0)

Converts images to the WebP format.

If your user's browser supports the WebP format, your images are automatically converted to this format.

Allowed values: boolean

Default value: true

pjpeg (since 1.5.0)

Converts JPEG images to the progressive format.

Progressive JPEG images have a smaller file size and are faster for the browser to load. The format achieves this by saving the image data in ascending quality so that a previous version of the image can be displayed at first. This improves the First Meaningful Paint of your website especially where large JPEG images are used.

Allowed values: boolean

Default value: true

crop (since 1.5.0)

Crops images to the specified dimensions.

This option allows you to crop your images to specific sizes. If you specify a string, you can give an aspect ratio, e.g., "16:9", "4:3". Specify an array of two numbers to smartly crop the image to a specific width and height. If you specify an array of four numbers, the first two values are interpreted as X and Y coordinates and the last two values as width and height. To disable cropping, just specify false.

Allowed values: false | string | [number, number] | [number, number, number, number]

Default value: false

Example value: [20, 10, 200, 400]
Crops a 200 × 400 pixel area from 20 pixels on the X axis and 10 pixels on the Y axis.

ImageRule

An image rule selects a subset of images and applies some ImageOptions to it. See the image option for more information.

enabledSites (since 1.9.0)

The sites on which this image rule is enabled.

Allowed values: SpeedKitRule[]

Example value: [{ "pathname": "/product/details/" }]
In this example, Speed Kit will apply image options given by the options property to all images requested from a product details page under the path of "/product/details/". All other images will not be affected by this rule.

rules (since 1.5.0)

The rules to match only some images.

Allowed values: SpeedKitRule[]

Example value: [{ "pathname": "/images/photos/" }]
In this example, Speed Kit will apply image options given by the options property to all images under the "/images/photos/" path. All other images will not be affected by this rule.

options (since 1.5.0)

required The options to apply to the selected images.

Allowed values: ImageOptions

Example value: { quality: 75, webp: false }
Applies a quality of 75% and disables WebP support for all images affected by this rule.

ResourceRule

A resource rule selects a subset of critical resources.

enabledOn (since 1.11.0)

The pages from which the critical resources should be fetched.

Allowed values: SpeedKitRule[]

Example value: [{ host: "www.baqend.com" }]
In this example, Speed Kit will fetch the critical resources given by the resources property for the given page.

resources (since 1.11.0)

required The critical resources to fetch before any other resources.

Allowed values: string[]

Example value: ["https://www.baqend.com/style.css"]
In this example, Speed Kit will fetch the "style.css" file with high priority.

ContentType

An enumeration classifying the content of a request.

Value Description
"document" Applies to HTML documents.
"audio" Applies to audio files like MP3, WAV, or OGG.
"video" Applies to resources which are videos.
"track" Applies to resources which are subtitle tracks of the WebVTT format.
"image" Applies to resources which are images.
"style" Applies to resources which are style sheets.
"script" Applies to resources which are JavaScript files.
"font" Applies to resources which are fonts.

Condition

Conditions are statements which are tested against strings, they can either be:

  • a String which is treated as a prefix against the given subject,
  • a Regular Expression which is tested against the given subject,
  • or an Array of Conditions for which one of its items has to match agains the subject.

Examples

"hello" The subject has to start with “hello”.
["hello", "world"] The subject has to start with either “hello” or “world”.
/^hello world$/ The subject has to start and end with “hello world”.
/^hello world$/i The subject has to start and end with “hello world” case-insensitively.
['hello', /hello$/] The subject has to either start or end with “hello”.