Speed Kit Configuration
Key Takeaways
- Centralized Centralized configuration: The Speed Kit configuration file is a powerful, flexible tool for managing the behavior of the Speed Kit service. It allows for granular control over which pages and resources are accelerated to ensure optimal performance.
- Granular, rule-based control: The core of the Speed Kit configuration is its comprehensive rule system. It allows you to define precise rules using matchers for hostnames, pathnames, URLs, and content types, giving you fine-grained control over caching and optimization behaviors.
- Safe and progressive optimization: Speed Kit's default configuration is built for safety and reliability. By using distinct rules for enabled sites and whitelisting critical resources, the system ensures that acceleration is only applied where it is intended, preventing unwanted side effects while maximizing performance.
Introduction
The Speed Kit configuration is the central control hub for the Speed Kit acceleration service. This JavaScript-based configuration defines exactly how Speed Kit should behave on your website, from which pages to accelerate to which resources to optimize. It works in conjunction with the core service worker logic (typically found in wrapper-sw.js).
This document serves as a comprehensive guide for developers and technical stakeholders. It breaks down the core components of the configuration, explains the logic behind its rule-based system, and provides practical examples to help you understand and modify your site's performance settings.
The Core Configuration
The Speed Kit configuration, housed in a configuration script that is included in the installation resource (typically placed in the <head> of your HTML), is the central control hub for the Speed Kit acceleration service. This configuration works in conjunction with the wrapper-sw.js file, which contains the core service worker logic. This configuration defines exactly how Speed Kit should behave on your website, from which pages to accelerate to which resources to optimize.
This configuration object is generated dynamically by Speed Kit, using rules and settings from different sources. You can influence and update these settings through multiple channels:
- Speed Kit Dashboard: The primary interface for business and project managers to manage and test configurations.
- Speed Kit Product Integration Team: For complex or fundamental changes, our team manages the updates directly in the configuration code.
Basic Configuration Properties
The following properties are typically found in every Speed Kit configuration.
- appName: A unique identifier for your application within the Speed Kit ecosystem. This value is managed internally and does not need to be changed by the customer.
- sw: This property specifies the path to your Speed Kit service worker file (e.g., /wrapper-sw.js). This value should only be updated if your e-commerce platform requires the file to be located at a different path or file name.
- preloadDynamicBlocks: A boolean that enables or disables Speed Kit's core "race" feature. When set to true (the default), the system races a request to the Speed Kit cache against a request to your origin server. For purely static sites, where no dynamic content needs to be merged, this can be set to false.
- rumTracking: A boolean that controls whether Real User Monitoring (RUM) data is sent to the Speed Kit backend. When set to false, no RUM data will be collected.
- split: A value between 0.0 and 1.0 that determines the percentage of users for whom Speed Kit will be active. This is primarily used for A/B testing during the onboarding and proof-of-concept (POC) phase.
- splitTestId: A unique string identifier for your A/B test. This is used to distinguish between different test iterations and is used in conjunction with the split property for segmenting user data in performance reports.
- disabled: This property allows you to completely disable Speed Kit for a specific user segment. It is primarily used for troubleshooting, for example, if an issue is identified in a particular browser version. When this condition is met, the service worker will not be installed, and no acceleration will occur for that segment.
window.speedKit = {
appName: APP,
sw: "/wrapper-sw.js",
preloadDynamicBlocks: true,
rumTracking: true,
split: 0.5,
splitTestId: "50vs50-test-id",
// Example: Disable Speed Kit for a specific version of Microsoft Edge
disabled: /Edge\/18\.17763/.test(navigator.userAgent),
};The Rule-Based System
Most of Speed Kit's functionality is governed by a powerful, rule-based system. This system provides a flexible way to define and apply specific behaviors to different parts of your website, such as accelerating or excluding pages and resources, optimizing images, and stripping query parameters.
Understanding the Rule Structure
At its core, the rule system uses an array of objects. Each object in the array represents a rule, and all rules are linked by an OR operator. This means if a request matches any of the rules in the array, the rule set is considered to have a match.
Within each rule object, the properties are linked by an AND operator. This means for a rule to be considered a match, a request must satisfy all the conditions within that rule object.
Example:
[
{
pathname: [
/\/cart/i,
/\/my-account/i,
],
host: ["example.com","imagesrv.com","connect.social.com"],
},
{
pathname: "/contact/"
},
];
In this example, a request will be accelerated if it matches (one of the pathnames AND one of the hosts) OR (/contact/ and all its sub-resources). This shows how rules can be combined to accelerate specific resources on a variety of different hosts, while also enabling acceleration for a simple pathname on any host where the install-resource is integrated and enabled.
Rule Matchers
All rule-based properties support the following matchers. Each matcher can accept a string, a regular expression (regex), or an array of strings and regexes. A single rule can also combine different matcher types.
String and Regex Matchers
String Matchers: For host, pathname, and url, string matchers perform a prefix match after converting both the input and the matcher to lowercase. This is useful for automatically including sub-resources (in the case of a path) or query parameters (in the case of a URL).
- String Matchers: For host, pathname, and url, string matchers perform a prefix match after converting both the input and the matcher to lowercase. This is useful for automatically including sub-resources in the case of a path.
- Regex Matchers: Regexes provide more control and are typically used for more complex patterns. It is recommended to use the /i flag to ensure the regex is case-insensitive.
Matcher Types
Here are concrete examples for each matcher type to demonstrate how to use them in a configuration.
- host: Matches the hostname of the URL. This is a crucial rule for whitelisting both your own domain and any third-party hosts you want to accelerate. It is often an array to include multiple hosts.
// A host rule matching an array of domains
host: "www.example.com"
- pathname: Matches the path of the URL. A rule for /about/ would also match /About/team and /about/company.
// A pathname rule matching the home page and all blog posts
pathname: [/^\/$/, "/blog/"]
- url: Matches the full URL, ignoring the protocol part. The match must start with the domain name and can be combined with a path and query parameters (e.g., www.example.com/my-path).
// Matches www.example. URLs with 4 or more path segments.
url: /^www\.example\.[\w.]+(\/[\w_-]+){4,}$/,
// Matches a specific URL prefix, including its path components (prefix match).
url:"www.example.com/products/view",
// Excludes pages containing a specific query parameter from being accelerated (regex).
url: /[?&]exclude_cache=true/i,
- contentType: Matches the resource's content type (e.g., navigate, script, style, image, font). A rule with contentType: ["navigate"] will only match the top-level HTML document and will not apply to any sub-resource requests, like xhr/fetch requests, scripts, styles, fonts, and images.
// A contentType rule matching only images and fonts
contentType: ["image", "font"],
- cookie: Matches a cookie's presence or value. This is useful for segmenting users based on login status or a/b test groups.
// A cookie rule checking for a specific session cookie
cookie: "session_id",
cookie: "logged_in=1",The Two Layers of Rules
The Speed Kit rule system is applied in two distinct layers:
- Navigation-level rules: enabledSites and disabledSites determine if a given page navigation is eligible for acceleration.
- Resource-level rules: whitelist and blacklist determine which specific resources on that page will be accelerated.
A page must first be deemed eligible for acceleration at the navigation level before the resource-level rules can take effect.
enabledSites vs. disabledSites: Navigation-Level Control
These rules determine if a page navigation is eligible for acceleration by Speed Kit. They are the first layer of control that operates on a page-by-page basis. If enabledSites is not defined, all pages are considered enabled by default. Similarly, if disabledSites is not defined, no pages are disabled by default.
A page must match an enabledSite rule and must not match a disabledSite rule to be considered for acceleration.
- enabledSites: This property defines which pages and sections of your site are eligible to be accelerated. It's often used as an explicit allowlist for acceleration.
- disabledSites: This property defines pages that should be explicitly excluded from acceleration. A page on the disabledSites list will not be accelerated, even if it also matches an enabledSites rule.
Example: Combining enabledSites and disabledSites
This configuration ensures that Speed Kit's core logic is only active on the homepage, category pages, and product detail pages. A specific sub-page within the category section is then explicitly excluded.
window.speedKit = {
//... other properties
enabledSites: [
{
pathname: [
/^\/$/, // Home
/^\/en\/$/, // Home
/\/category/i, // Category & PLP
/\/product/i, // PDP
],
},
],
disabledSites: [
{
pathname: /\/category\/specific-page-to-exclude/i,
},
],
};Whitelist vs. Blacklist: Resource-Level Control
The whitelist and blacklist are a granular layer of control that operates on pages already enabled for acceleration. They are used to define which specific resources (e.g., images, scripts, fonts) should be accelerated.
A resource is accelerated only if it is on the whitelist and is not on the blacklist. The blacklist always takes precedence.
- Whitelist: Used to explicitly enable acceleration for specific first- and third-party resources and content types (e.g., HTML, images, CSS, or scripts from a third-party CDN).
- Blacklist: Used to explicitly prevent acceleration for specific resources or content types that are problematic, such as those with non-deterministic query parameters or sensitive data (e.g., certain third-party scripts, video files, or PDFs).
These rules are a more granular layer of control that operates only on pages that are already confirmed as an enabled site. They are used to define which specific resources on those pages should be accelerated.
A navigation or resource will only be accelerated if it is explicitly whitelisted and is not on the blacklist. The blacklist always takes precedence over the whitelist.
Example: A typical whitelist configuration
window.speedKit = {
//... other properties
whitelist: [
{
host: "www.example.com",
contentType: ["navigate"],
},
{
host: ["fonts.googleapis.com", "fonts.gstatic.com"],
contentType: ["script", "style", "font"],
},
],
};
- The first rule whitelists all navigable content (i.e., HTML pages) for the enabled hosts.
- The second rule whitelists all script, style, and font files from Google's content delivery network (CDN). This is a common practice to accelerate third-party assets like Google Fonts.
Example: A typical blacklist configuration
window.speedKit = {
//... other properties
blacklist: [
{
// Exclude specific content types
contentType: ["audio", "video", "pdf"],
},
{
// Exclude specific third-party domains
host: ["adition.com", "imagesrv.adition.com",
"connect.facebook.net"],
},
{
// Exclude resources with specific query parameters
url: [/[?&]nocache/i, /\?time=\d+/i],
},
{
// Exclude all resources from a specific path
pathname: [/\/backend/i],
},
},
],
};
This blacklist ensures that any request matching these paths or URLs will not be accelerated, providing a safety net for business-critical and security-sensitive sections of your site.
Example: Optimize images on the cart page
Despite the cart page not being cached or accelerated, we still aim to optimize its images.
window.speedKit = {
//... other properties
enableSites: [
{
pathname: ["/product", "/cart"]
},
],
blacklist: [
{
// Cart navigation is not accelerated
pathname: "/cart",
},
],
whitelist: [
{
// Images on the cart page are accelerated
host: "images.example.com",
},
],
};Advanced Configuration
Image Optimization
Speed Kit provides powerful, browser-aware image optimization. Since most customers already use an existing image optimization solution, this feature is optional and should only be enabled when no other solution is in place to avoid technical conflicts. We offer this feature for clients that currently do not have a dedicated image optimization solution. For more detailed information on available settings, refer to the ImageOptions interface specification.
image: This property allows you to fine-tune the image optimization settings.
- quality: You can set the compression quality (high, medium, or low), which corresponds to the level of visual fidelity.
- webp: A boolean flag to enable or disable WEBP delivery. Default is true.
- avif: A boolean flag to enable or disable AVIF delivery. Default is false.
Note on AVIF & WEBP: Do not activate AVIF if your origin server delivers WEBP images, as converting an already compressed image to AVIF can introduce visible artifacts. AVIF is delivered only when enabled and supported by the browser; otherwise, the system automatically delivers WEBP as a fallback.
Example:
window.speedKit = {
//... other properties
image: {
quality: "high", // Default is "medium"
webp: true, // Default is "true"
avif: true, // Default is "false"
},
whitelist: [
{
host: "images.example.com",
contentType: ["image"],
},
],
};Stripping Query Parameters
To improve your cache hit ratio, Speed Kit can be configured to strip query parameters that are used for tracking or analytics but do not change the page's content. A unique URL with a different query parameter would otherwise be treated as a separate page, leading to a cache miss.
This configuration only affects the URL used to load the resource from Speed Kit's cache. The URL visible in the user's browser is not changed. Additionally, the original URL with all of its parameters is still used for the request to your origin server, ensuring that all backend logic, tracking, and analytics function correctly.
Example:
window.speedKit = {
stripQueryParams: [
{
params: [
// Analytics and Tracking:
"_ga",
"_gl",
"fbclid",
"utm_campaign",
"utm_medium",
"utm_source",
"msclkid",
"gclid",
"srsltid",
],
},
],
};
As with other rules, you can also add a rule set to a specific parameter, allowing you to only strip that parameter on a specific page or URL pattern. For example, stripping a search query parameter on a page where it's not relevant.
window.speedKit = {
stripQueryParams: [
{
pathname: /^\/search-results/,
params: ["q"],
},
],
};User Agent & Device Detection
For websites with separate mobile and desktop versions, Speed Kit can replicate your server-side logic to serve the correct cached version to the user.
- userAgentDetection: A boolean that, when set to true, enables an internal User Agent detection. This feature uses a standard set of rules to determine whether a user is on a desktop or mobile device.
- detectDevice: This advanced property takes a function that accepts the document's HTML as an argument. Its primary purpose is to extract the device type directly from the origin HTML response, ensuring Speed Kit's device detection logic is perfectly aligned with your backend. You should use this function to check for a specific indicator that your server-side code adds, such as a CSS class or a meta tag that is only present on the mobile or desktop version of the page. This guarantees that Speed Kit serves the correct, device-specific cached content to the user.
Example:
window.speedKit = {
//... other properties
userAgentDetection: true,
detectDevice: (doc) => {
// Check for a specific CSS class to determine the device type
return doc.querySelector(".mobile,.is-mobile") ? "mobile" : "desktop";
},
};Documenting and Maintaining Your Configuration
The Configuration Dashboard
The Speed Kit Dashboard provides a central location for you to manage, view, and test your configuration. The Speed Kit Dashboard provides a central location for you to manage, view, and test your configuration.
You can create and test multiple configurations before deploying them to your live site. For more detailed information on this process, refer to the "Quality Assurance: How to Test Speed Kit" documentation.
Best Practices
- Keep it clean: Avoid overly complex configurations. Start with simple rules and add complexity only when a specific use case requires it.
- Prioritize the blacklist: When in doubt, it is safer to blacklist a page or resource to prevent unwanted side effects.
- Communicate planned changes: Inform Speed Kit about any planned changes that require a configuration update: Website Changes Requiring Speed Kit Configuration Updates for Optimal Performance.
- Leverage our experts: Our Product Integration team and web performance specialists are trained to build and maintain these configurations. They can help you with complex scenarios and ensure your configuration is always optimized for your specific needs.
