Umbraco Turbo Pro

Script Queue — Loading JS from Block Components

The Problem

uTPro uses a deferred loading strategy — jQuery and plugins only load after user interaction (or 3s idle) to improve Core Web Vitals. This creates a challenge:

If a block component renders its own <script defer> tag, it may execute before jQuery is available — causing $ is not defined errors.

Timeline:
├─ HTML parsed → component <script defer> executes immediately  ❌ jQuery not loaded yet
├─ User interacts (or 3s idle)
└─ jQuery + plugins start loading

The Solution: Script Queue

Components register their JS file paths into a per-request queue. The Layout then renders them in the correct position — either inside the deferred loader (after jQuery) or as standalone <script defer> tags.

Component.cshtml → Html.QueueScript() or Html.QueueStandaloneScript()
                         ↓
              HttpContext.Items (per-request, dedup)
                         ↓
_Layout.cshtml  → @Html.RenderScriptQueue()        → appends to deferred array
                → @Html.RenderStandaloneScripts()   → renders <script defer> tags

Two Methods

Both methods deduplicate automatically — same script registered twice = rendered once.

Usage in Component

@if (Context.Request.IsBlockPreviewRequest())
{
    @* Preview mode: CSS only, no JS needed *@
    <link rel="stylesheet" href="~/css/@CurrentSite.GetItem().Root.Name/Components/MyComponent.css" />
}
else
{
    @using (Html.SetSection(Model.GetType().ToString(), HtmlSectionBlockExtensions.Position.BodyBottom))
    {
        <link rel="stylesheet" href="~/css/@CurrentSite.GetItem().Root.Name/Components/MyComponent.css" />
    }

    // QueueStandaloneScript: vanilla JS, no dependencies, loads via <script defer>
    // QueueScript: needs jQuery, appended to deferred loader chain (loads AFTER jQuery)
    Html.QueueStandaloneScript($"/scripts/{CurrentSite.GetItem().Root.Name}/my-component.js");
}

Example: Script that needs jQuery

Html.QueueScript($"/scripts/{CurrentSite.GetItem().Root.Name}/slider.js");

Example: Standalone script (no jQuery)

Html.QueueStandaloneScript($"/scripts/{CurrentSite.GetItem().Root.Name}/cookie-consent-banner.js");

What Happens in the Layout

<!-- Deferred loader: jQuery + plugins + QueueScript entries -->
<script>
    (function(){
        var scripts=[
            '/assets/scripts/jquery.min.js',
            '/assets/scripts/jquery.dropotron.min.js',
            '/scripts/uTPro/util.js',
            '/scripts/uTPro/main.js'
            ,'/scripts/uTPro/slider.js'        // from QueueScript
        ];
        // loads sequentially after user interaction or 3s idle
    })();
</script>

<!-- Standalone scripts: QueueStandaloneScript entries -->
<script src="/scripts/uTPro/cookie-consent-banner.js" defer></script>

Rules

1. Vanilla JS (no dependencies) → QueueStandaloneScript
2. Needs jQuery or any library in the deferred chain → QueueScript
3. Never put <script src="..."> directly in a component — use the queue
4. CSS can still use SetSection as before (no dependency ordering issues)
5. Both methods are safe to call multiple times with the same path — dedup is automatic

Architecture

Implemented in uTPro.Extension/ScriptQueueExtensions.cs:

• Uses HttpContext.Items for per-request storage (zero serialization cost)
• HashSet<string> for O(1) dedup
• HTML-encodes paths to prevent XSS
• Two separate queues (deferred vs standalone) with independent storage keys