feat: dual-mode JQuery/native DOM backend

[dupontbertrand]

Here's the jQuery PR. Since this is a critical change, I had Claude help draft a comprehensive write-up covering the approach, benchmarks, and open questions — it's a bit long but I wanted to make sure everything is laid out clearly for review.

Context

Issue #490 discusses removing jQuery (~90KB) from Blaze's dombackend.js. As @jankapunkt noted, simply removing jQuery is a breaking change (instance.$() returns a plain Array instead of a jQuery object), unsuitable for a minor release.

This PR implements a dual-mode backend: jQuery is detected at load time. If present, all existing code paths are preserved (zero breaking changes). If absent, native DOM APIs are used. A deprecation message is logged when jQuery is detected.

Relationship with #474

PR #474 by @harryadel started exploring this direction by tackling parseHTML replacement. This PR builds on the same idea but extends it to the entire DOM backend:

	#474 (harryadel)	This PR
Scope	parseHTML (WIP, first step)	Full dombackend.js (parseHTML, events, teardown, findBySelector)
parseHTML approach	innerHTML + regex wrapping + sanitize-html	<template> element (3 lines, handles <tr>/<td> natively)
New dependencies	sanitize-html (npm)	None
jQuery still required?	Yes (remaining areas not yet addressed)	No — fully optional

Credit to @harryadel for initiating this effort and identifying the parseHTML path.

What changed

Single file modified: packages/blaze/dombackend.js (169 additions, 90 deletions)

All other Blaze files (domrange.js, events.js, template.js, package.js) required no changes — they already go through the DOMBackend abstraction.

Area	jQuery path (unchanged)	Native path (new)
parseHTML	$.parseHTML()	<template> element + content.childNodes
Event delegation	$.on(type, selector, handler)	addEventListener + event.target.closest(selector) + WeakMap cleanup
Event capture	$.event.fix() + $.is($.find())	closest() + elem.contains()
focus/blur	jQuery aliases internally	Explicit focus→focusin / blur→focusout aliasing
Teardown	$.cleanData() → jQuery special event	Direct _executeTeardownCallbacks() — no jQuery overhead
findBySelector	$(selector, context)	querySelectorAll() → plain Array

No existing tests were modified (per @jankapunkt's request in #490).

How it works — technical details

Detection (lines 4-18)

Before, Blaze would crash immediately without jQuery (throw new Error("jQuery not found")). Now:

const $jq = (typeof jQuery !== 'undefined' ? jQuery :
           (typeof Package !== 'undefined' && Package.jquery ?
            (Package.jquery.jQuery || Package.jquery.$) : null));
const _hasJQuery = !!$jq;

Every function in the file branches on _hasJQuery. jQuery present → existing code path. jQuery absent → native path.

parseHTML — why <template> works

When Blaze renders HTML (e.g. <div>{{name}}</div>), it needs to turn an HTML string into real DOM nodes.

PR #474 tried to do this with a <div> + regex detection for table elements. The problem: a regular <div> has HTML parsing constraints. If you do:

const div = document.createElement('div');
div.innerHTML = '<tr><td>hello</td></tr>';
console.log(div.innerHTML);  // "hello" — the <tr> and <td> are STRIPPED by the parser!

So #474 needed regex to detect <tr>, <td>, <th>, <thead>, etc. and wrap them in the correct parent element before parsing.

The <template> element developer.mozilla.org is special in the HTML spec. Its .content is a DocumentFragment with no parentage constraints — any HTML is valid inside it:

const tpl = document.createElement('template');
tpl.innerHTML = '<tr><td>hello</td></tr>';
console.log(tpl.content.firstChild);  // <tr> — intact!

The browser does all the work. No regex, no dependency, 3 lines:

const template = document.createElement('template');
template.innerHTML = html;
return Array.from(template.content.childNodes);

Event delegation — closest() + addEventListener

When you write:

Template.myTpl.events({
  'click .my-button'(event) { ... }
});

Blaze doesn't attach a listener on every .my-button. It attaches one listener on the parent container and checks if the click target matches the selector. This is "event delegation".

With jQuery: $jq(elem).on('click', '.my-button', handler) — jQuery handles it.

Without jQuery:

const wrapper = (event) => {
  const target = event.target.closest('.my-button');  // walk up the DOM
  if (target && elem.contains(target)) {              // check we're in the right container
    handler.call(target, event);
  }
};
elem.addEventListener('click', wrapper);

closest(selector) walks from event.target up through ancestors until it finds a match — exactly what jQuery does internally, but native.

A WeakMap stores the wrapper functions so they can be removed later in undelegateEvents.

focus/blur aliasing

focus and blur don't bubble — they don't propagate up the DOM, so delegation can't work with them. jQuery silently swaps them for focusin/focusout (which do bubble). We do the same explicitly:

const _delegateEventAlias = { focus: 'focusin', blur: 'focusout' };

Teardown — direct callback execution

When Blaze destroys a template (Blaze.remove()), it runs cleanup callbacks (stop autoruns, release subscriptions, etc.).

With jQuery, Blaze uses a clever hack: a "jQuery special event" (blaze_teardown_watcher). When jQuery cleans up an element ($.cleanData), it triggers the teardown handler that runs the callbacks. This is indirect and carries $.cleanData overhead.

Without jQuery, we call _executeTeardownCallbacks(elem) directly on each element — no detour through jQuery internals. This is why benchmarks show -57% to -67% on teardown: we skip all of $.cleanData's overhead.

findBySelector

if (_hasJQuery) return $jq(selector, context);
return Array.from((context || document).querySelectorAll(selector));

The only area where jQuery is slightly faster (+12%) — its internal selector engine wraps results with less overhead than Array.from(querySelectorAll()). In absolute terms: 1.7ms vs 1.9ms for 1,000 calls.

Benchmarks

Tested on identical apps — only difference is presence/absence of the jquery Meteor package.

Environment: Ubuntu 24.04, Chrome 145, Meteor 3.4, Node 22.13, ThinkPad P52 (i7-8850H, 64GB RAM)

DOM Operations (client-side, median of 5 runs)

Test	jQuery	Native	Delta
Render List (1K items)	5.30ms	4.80ms	-9%
Render List (10K items)	75.50ms	50.60ms	-33%
parseHTML x1,000	23.30ms	15.80ms	-32%
parseHTML x10,000	174.80ms	135.10ms	-23%
findBySelector x1,000	1.70ms	1.90ms	+12%
findBySelector x10,000	16.60ms	21.60ms	+30%
Event Delegation (500 items)	11.70ms	6.30ms	-46%
Event Delegation (5K items)	104.10ms	73.10ms	-30%
Teardown (500 elements)	5.40ms	2.30ms	-57%
Teardown (5K elements)	33.20ms	11.10ms	-67%

Summary: Native is faster on render, parseHTML, events, and teardown (up to 67%). jQuery is slightly faster on findBySelector, but the difference is negligible in absolute terms (1.7ms vs 1.9ms for 1,000 calls).

Reactive / MongoDB (network-bound)

No significant difference — the bottleneck is DDP + MongoDB, not the DOM layer.

Bundle size

Removing jQuery saves ~90KB minified (~30KB gzipped) from the client bundle.

Event coverage

Manually tested 30+ DOM event types in both apps (with and without jQuery), including non-bubbling events (mouseenter, mouseleave, scroll, pointerenter, pointerleave) which go through Blaze's capture mode. All work correctly with the native backend.

Open questions for discussion

1. TypeScript definitions (blaze.d.ts)

Currently blaze.d.ts has import * as $ from 'jquery' and types TemplateInstance.$() as JQuery<TElement>. Without jQuery, this returns a plain HTMLElement[]. Options:

• Conditional types / overloads
• Separate .d.ts for each mode
• Leave as-is and let users with jQuery augment types

Looking for guidance on preferred approach.

2. --no-jquery flag for meteor create

All Blaze skeletons (skel-blaze, skel-full, skel-legacy) currently include jQuery by default. A --no-jquery flag or an updated skeleton would make it easier for new projects to opt into the native backend. This would be a separate PR on meteor/meteor.

3. Documentation

A migration guide would be needed:

• How to remove jQuery from an existing Blaze app (meteor remove jquery)
• What changes: instance.$() returns HTMLElement[] instead of jQuery object
• How to check: search codebase for .$( calls that use jQuery-specific methods (.animate(), .fadeIn(), etc.)

4. Existing test suite

All 416 existing Blaze unit tests pass with jQuery present. The test for Array.isArray($found) at render_tests.js:621 would need a conditional check to also pass without jQuery — but per @jankapunkt's request, no tests were modified in this PR. Happy to add that in a follow-up.

How to test this yourself

# Clone and checkout
git clone https://github.com/dupontbertrand/blaze.git
cd blaze
git checkout dual-dom-backend

# Create a test app
meteor create test-app --blaze
cd test-app

# Point the app to the local Blaze packages
export METEOR_PACKAGE_DIRS=../packages

# Test WITH jQuery (default — should behave exactly as before)
meteor
# → Console shows: "[Blaze] jQuery detected as DOM backend..."
# → Everything works, instance.$() returns jQuery object

# Test WITHOUT jQuery
meteor remove jquery
meteor
# → No deprecation message
# → App works, instance.$() returns plain Array

Test plan

• App boots and runs without errors — with jQuery
• App boots and runs without errors — without jQuery
• instance.$() returns jQuery object (with jQuery) / plain Array (without)
• Event delegation works for 30+ event types in both modes
• Non-bubbling events (mouseenter, mouseleave, etc.) work via capture mode
• currentTarget correctly set on delegated events (verified with nested elements)
• Template teardown cleans up reactive computations in both modes
• Deprecation message logged when jQuery is present
• No deprecation message when jQuery is absent
• All 416 existing unit tests pass (with jQuery)
• Unit tests with native backend (blocked on render_tests.js conditional — follow-up)

Ref #490, relates to #474

[Copilot]

Pull request overview

This PR implements a dual-mode DOM backend for Blaze, making jQuery optional rather than required. When jQuery is present, all existing code paths are preserved. When absent, native DOM APIs are used. This is a single-file change to packages/blaze/dombackend.js that replaces the hard dependency on jQuery with a runtime detection mechanism, addressing issue #490 and building on the direction started by PR #474.

Changes:

• jQuery detection at load time with a deprecation notice, replacing the hard crash when jQuery is absent
• Native DOM implementations for parseHTML (using <template> element), event delegation (addEventListener + closest()), event capture, teardown callbacks, and findBySelector (querySelectorAll)
• Refactored jQuery special event registration and teardown callback execution into shared/conditional code paths

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[jankapunkt]

@dupontbertrand the last task item "Unit tests with native backend (blocked on render_tests.js conditional — follow-up)" will be added here or in another PR?

[dupontbertrand]

@dupontbertrand the last task item "Unit tests with native backend (blocked on render_tests.js conditional — follow-up)" will be added here or in another PR?

As you want, I think it's not that important right ? So I can do an other PR for that ? Tbh when I'm thinking about it now I don't see the added value since we keep JQ for the moment

[jankapunkt]

@dupontbertrand I will add the migration notes to my incoming PR for the new vitepress docs

[dupontbertrand]

@jankapunkt Do I need to think about "new templates" for --create ? Or change existing one for removing JQuery by default in the next release ?

[jankapunkt]

@dupontbertrand sorry I don't understand what do you exactly mean?

[dupontbertrand]

@jankapunkt Yes sorry : Shouldn’t the meteor create templates stop including jQuery by default? (--blaze and --full)

[jankapunkt]

Yes that's the skeleton that need to be updated but I wouldn't do that before we released 3.1 unless @italojs thinks otherwise

[jankapunkt]

@dupontbertrand I was close to merge this but I found, that tests currently only cover the jQuery implementation, however we should have tests in place that also test for the absence of jQuery not only for the sake of functionality but also for preventing regressions in the future.

[dupontbertrand]

Omw boss 🧐🫡

[dupontbertrand]

@jankapunkt

I want to make sure I understand the expected testing scope correctly 😬

Right now, as long as tests load jQuery strongly, Blaze._DOMBackend._hasJQuery is always true, so the native path is never actually exercised

How do you see the right approach here?

1. Remove jQuery from the test setup entirely?

2. Rework the tests so jQuery is loaded conditionally / dynamically, and run the suite in both modes ?

3. Keep the current global test setup unchanged, but add a small internal way to force Blaze._DOMBackend into native mode for specific tests, so we can run the same assertions against the no-jQuery path too

Which direction would you prefer ?

[jankapunkt]

@dupontbertrand I think we should leverage Meteor.isTest or Meteor.isDevelopment to attach a Method that enables to switch to native mode.

Let me try to draft something today.

[jankapunkt]

Uhm where does this coderabbitai come from?

[dupontbertrand]

@nachocodoner 👀 ?

[nachocodoner]

We added it on Meteor project recently to expeirment on that AI tool, trying to make it less noisy in this PR, meteor/meteor#14271

What I can't understand is why it affects all meteor repos. I will talk with @fredmaiaarantes as he may activated for the whole organization.

[harryadel]

Thank you @dupontbertrand for your amazing efforts
@jankapunkt I think running coderabbit here would be beneficial. But I wouldn't initiate it without you approve it first.
I gave the changes a read and they seem ok initially but definitely getting a second eye is important

[harryadel]

As for the open questions:

1. TypeScript definitions (blaze.d.ts)

I'm no typescript dude so I'll defer it to those who know better @radekmie @perbergland @wreiske @ebroder

2. --no-jquery flag for meteor create

Seems like a great addition to be honest but definitely requires some work and coordination with @nachocodoner as he's already updating examples - meteor/examples#42

3. Documentation

Actually I'd say a little changelog would suffice with very few examples. Because it's a straight forward. But maybe this is me.

4. Existing test suite

I'd follow suite with what @jankapunkt's requests, as he's A) an old trusted contributor B) uses Blaze on an everyday basis and still cares about it

[jankapunkt]

For new Projects I think we do not need a --no-jquery flags but just update the package list in the skeleton, once 3.1.0 is out or am I missing something?

[dupontbertrand]

@jankapunkt I think @harryadel meant suggesting examples both with and without jQuery ?

[jankapunkt]

@dupontbertrand I am merging this into the release-3.1.0 release and work on the tests there.

[jankapunkt]

@dupontbertrand please review the follow-up #497