[TURBO-101] How Storefront Loads in Browser, Technically?

This guide explains the technical architecture behind how Boost TURBO integrates with Shopify themes and loads in the browser.

App Block Integration Overview

After installing Boost TURBO, merchants integrate the app functionality by enabling the related Theme App Extension (TAE) app embed block. This creates a seamless integration point within the theme's liquid templates.

Identifying App Block Integration

You can verify the integration by viewing the page source in the storefront. Look for the BEGIN app block keyword to locate our app block's deep link:

Browser Loading Sequence

Here's the step-by-step process of how the app block loads and renders in the storefront:

1. Initial Page Request

• User navigates to a storefront URL in their browser
• Shopify server processes the request and identifies the active theme

2. Theme App Extension Loading

• Shopify server loads the linked TAE app block (written in Liquid)
• App block retrieves app-owned metafields containing configuration data

3. HTML Generation

• App block generates initial client-side script tags and HTML blocks
• Shopify renders the complete page HTML and sends it to the browser

4. Client-Side Initialization

When the browser receives the page, the app block's client script executes:

1. Remote Asset Loading

   • Loads core JavaScript and CSS files
   • Loads customization assets specific to the store configuration

2. Configuration Setup

   • Initializes environment-specific settings
   • Constructs the core configuration object: window.boostWidgetIntegration

3. API Communication

   • Sends requests to Frontend API endpoints to retrieve:
     • Filter options for client-side behavior
     • Server-side rendered (SSR) HTML for initial page load

Core Configuration: window.boostWidgetIntegration

The boostWidgetIntegration object serves as the central configuration hub that you can inspect in the browser console.

Environment Separation

window.boostWidgetIntegration.app[env];

The configuration uses environment-based separation (env) to prevent conflicts when stores have both production and staging versions installed.

Key Configuration Properties

boostWidgetIntegration.app[env].template

Stores the compiled code for feature blocks, used by the frontend library for client-side re-rendering.

boostWidgetIntegration.app[env].templateMetadata

Contains template metadata including:

• Feature block file names
• CSS link references
• Template version information
• Asset URLs and checksums

boostWidgetIntegration.app[env].templateSettings

Stores feature block style configurations such as:

• Layout preferences
• Typography settings
• Color schemes
• Component-specific styling options

Next Steps

• Learn about customizing JavaScript behavior
• Explore template widget development
• Understand the overall TURBO architecture