jQuery 4.0.0: co się zmienia po dekadzie i jak bezpiecznie zrobić upgrade

14 stycznia 2006 John Resig pokazał na BarCamp w Nowym Jorku bibliotekę, która przez lata stała się domyślnym „klejem” dla frontendu: jQuery. Dokładnie 20 lat później zespół jQuery ogłosił finalne wydanie jQuery 4.0.0 – pierwszą dużą wersję od niemal dekady.

To wydanie jest wyraźnie modernizacyjne: po długim cyklu rozwoju i kilku pre-release’ach wchodzi sporo porządków, ale też kilka zmian niekompatybilnych wstecz. Dobra wiadomość jest taka, że według autorów większość projektów powinna przejść na 4.0.0 z minimalnymi poprawkami – pod warunkiem, że podejdziesz do aktualizacji świadomie.

Na start warto wiedzieć o dwóch narzędziach, które mają ułatwić przejście: oficjalnym przewodniku aktualizacji Upgrade Guide oraz wtyczce jQuery Migrate (plugin, który wykrywa i pomaga obsłużyć stare zachowania/API). Linki znajdziesz w sekcji źródeł.

Najważniejsza informacja: to duża wersja i są breaking changes

jQuery 4.0.0 usuwa sporo rzeczy, których nie dało się „wyciąć” w patchach i minorach: przycięto kod legacy, usunięto wcześniej zdeprecjonowane API, wywalono wewnętrzne parametry, które przez przypadek były dostępne w publicznych funkcjach (i nigdy nie były udokumentowane), a także zrezygnowano z części „magicznych” zachowań, które komplikowały utrzymanie.

Koniec wsparcia dla IE < 11 (i kilku bardzo starych przeglądarek)

jQuery 4.0 usuwa wsparcie dla IE 10 i starszych. Naturalne pytanie brzmi: dlaczego nie od razu IE 11? Zespół zapowiedział etapowe podejście – kolejny krok ma nastąpić w jQuery 5.0 (jest to już powiązane z pracami w repozytorium). Na ten moment z kodu znika wszystko, co było specyficzne dla IE < 11.

Równolegle ucięto wsparcie dla innych bardzo starych środowisk: Edge Legacy (stary EdgeHTML, nie Chromium), iOS starszy niż ostatnie 3 wersje, Firefox starszy niż ostatnie 2 wersje (z wyjątkiem Firefox ESR) oraz Android Browser. Po stronie większości projektów nie powinno to wymagać zmian – ale jeśli wciąż musisz obsługiwać te przeglądarki, rekomendacja jest prosta: zostań na jQuery 3.x.

Trusted Types i CSP: jQuery dogania współczesne polityki bezpieczeństwa

W 2026 roku coraz częściej spotykasz twarde ustawienia Content Security Policy (CSP), a w szczególności dyrektywę require-trusted-types-for, która ma ograniczać ryzyko XSS poprzez wymuszenie kontrolowanego wstrzykiwania HTML. jQuery 4.0 dodaje wsparcie dla Trusted Types, tak aby HTML opakowany w TrustedHTML (interfejs webowy opisany m.in. na MDN) mógł być przekazywany do metod manipulacji DOM bez łamania tej dyrektywy.

Druga część tej historii dotyczy AJAX-a i ładowania skryptów. Część requestów już wcześniej była realizowana przez tagi <script> (żeby utrzymać atrybuty typu crossdomain). Teraz jQuery poszło dalej: większość asynchronicznych requestów po skrypty przełączono na <script> tagi, żeby unikać błędów CSP związanych z inline scriptami.

W skrócie: jeśli masz projekt z ostrym CSP, to w 4.0 jest sporo pracy „pod maską”, która ma zmniejszyć liczbę zaskoczeń w produkcji.

Migracja źródeł jQuery do ES Modules

Jedna z najważniejszych modernizacji to migracja źródeł jQuery na gałęzi main z AMD (model znany m.in. z RequireJS) do ES modules (ESM). Do tej pory kod źródłowy był publikowany na npm i GitHubie, ale nie dało się go sensownie importować jako modułów bez RequireJS – bo to był historycznie preferowany tool do buildowania.

Teraz paczkowanie odbywa się przez Rollup, a testy są uruchamiane osobno również na wersji modułowej. To sprawia, że jQuery łatwiej „dogaduje się” ze współczesnymi bundlerami i workflow oraz z przeglądarkami, które obsługują <script type=module>.

Usunięte zdeprecjonowane API: lista i zamienniki

W jQuery 4.0.0 znikają funkcje zdeprecjonowane od kilku wersji – część była zawsze pomyślana jako wewnętrzna, a część ma dziś natywne odpowiedniki we wszystkich wspieranych przeglądarkach.

• jQuery.isArray
• jQuery.parseJSON
• jQuery.trim
• jQuery.type
• jQuery.now
• jQuery.isNumeric
• jQuery.isFunction
• jQuery.isWindow
• jQuery.camelCase
• jQuery.nodeName
• jQuery.cssNumber
• jQuery.cssProps
• jQuery.fx.interval

W praktyce przechodzisz na natywne rzeczy typu Array.isArray(), JSON.parse(), String.prototype.trim() czy Date.now().

Efekt uboczny tych porządków plus usunięcie kodu pod stare IE jest namacalny: rozmiar biblioteki zmniejszył się o ponad 3 kB (gzipped).

Zmiany w prototypie jQuery: znikają push/sort/splice

W prototypie jQuery od dawna wisiały metody Array (push, sort, splice), które nie zachowywały się jak typowe metody jQuery i były traktowane jako wewnętrzne. W 4.0 zostały usunięte.

Jeśli ktoś (świadomie lub przypadkiem) robił coś w stylu $elems.push( elem ), to teraz powinien przejść na wywołanie z pożyczaniem metody z Array:

// jQuery 3.x (działało, ale to było „wewnętrzne” zachowanie)
// $elems.push(elem)

// jQuery 4.x – zamiennik
[].push.call($elems, elem);

// jQuery 3.x (działało, ale to było „wewnętrzne” zachowanie)
// $elems.push(elem)

// jQuery 4.x – zamiennik
[].push.call($elems, elem);

Kolejność eventów focus/blur zgodna z W3C (breaking change)

Przez lata przeglądarki nie mogły się dogadać co do kolejności eventów focus/blur (w tym focusin, focusout, focus, blur). Wreszcie najnowsze wersje przeglądarek wspieranych przez jQuery 4.0 ujednoliciły zachowanie – ale… nie jest to ta kolejność, którą jQuery trzymało konsekwentnie przez lata. I to jest breaking change.

Od jQuery 4.0 biblioteka nie nadpisuje już natywnego zachowania. W efekcie wszystkie przeglądarki poza IE stosują aktualną specyfikację W3C w kolejności:

1. blur
2. focusout
3. focus
4. focusin

Dla porównania, w poprzednich wersjach jQuery kolejność wyglądała tak: focusout, blur, focusin, focus. Ciekawostka: jedyną przeglądarką, która trzymała się starej wersji specyfikacji (sprzed aktualizacji z 2023) był Internet Explorer.

Slim build jeszcze szczuplejszy: bez Deferreds i Callbacks

W jQuery 4.0.0 wariant slim zrobił się jeszcze mniejszy: usunięto z niego moduły Deferreds i Callbacks. Rozmiar slim builda to teraz około 19.5 kB (gzipped).

Deferreds od dawna wspierały standard Promises A+, więc w większości przypadków możesz przejść na natywne Promise. Te są dostępne we wszystkich przeglądarkach wspieranych przez jQuery 4.0 poza IE11. Deferreds mają kilka dodatkowych możliwości, których Promise nie ma, ale typowe użycia da się przepisać na metody Promise.

Warto też zapamiętać filozofię slim: czasem nie potrzebujesz AJAX-a (albo wolisz osobną bibliotekę stricte pod requesty), a animacje ogarniesz CSS-em plus manipulacją klasami. Dodatkowo natywne Promise (poza IE11) zdejmują potrzebę Deferreds/Callbacks w typowych zastosowaniach. Slim jest też ok. 8 kB (gzipped) mniejszy od pełnej wersji.

Skąd pobrać jQuery 4.0.0 (CDN, npm) + pliki slim

Wydanie jest dostępne na oficjalnym CDN jQuery oraz w npm. Zewnętrzne CDN-y (third-party) zwykle dodają pliki z opóźnieniem – autorzy przypominają, że ich harmonogramem jQuery nie zarządza.

• CDN: https://code.jquery.com/jquery-4.0.0.js
• CDN (min): https://code.jquery.com/jquery-4.0.0.min.js
• npm: npm install jquery@4.0.0
• Slim: https://code.jquery.com/jquery-4.0.0.slim.js
• Slim (min): https://code.jquery.com/jquery-4.0.0.slim.min.js
• Więcej metod instalacji: https://jquery.com/download/

Changelog 4.0.0: przegląd zmian moduł po module

Poniżej zebrałem pełną listę punktów z changeloga opublikowanego przez jQuery. Jeśli robisz upgrade w większej aplikacji, dobrze jest przynajmniej przeskanować sekcje, które dotykają używanych przez ciebie obszarów (AJAX, eventy, selektory, manipulacja DOM).

Full changelog

Pełne porównanie zmian: 4.0.0

Ajax

• Don’t treat array data as binary (992a1911)
• Allow processData: true even for binary data (ce264e07)
• Support binary data (including FormData) (a7ed9a7b)
• Support headers for script transport even when cross-domain (#5142, 6d136443)
• Support null as success functions in jQuery.get (#4989, 74978b7e)
• Don’t auto-execute scripts unless dataType provided (#4822, 025da4dd)
• Make responseJSON work for erroneous same-domain JSONP requests (68b4ec59)
• Execute JSONP error script responses (#4771, a1e619b0)
• Avoid CSP errors in the script transport for async requests (#3969, 07a8e4a1)
• Drop the json to jsonp auto-promotion logic (#1799, #3376, e7b3bc48)
• Overwrite s.contentType with content-type header value, if any (#4119, 7fb90a6b)
• Deprecate AJAX event aliases, inline event/alias into deprecated (23d53928)
• Do not execute scripts for unsuccessful HTTP responses (#4250, 50871a5a)
• Simplify jQuery.ajaxSettings.xhr (#1967, abdc89ac)

Attributes

• Make .attr( name, false ) remove for all non-ARIA attrs (#5388, 063831b6)
• Shave off a couple of bytes (b40a4807)
• Don’t stringify attributes in the setter (#4948, 4250b628)
• Drop the toggleClass(boolean|undefined) signature (#3388, a4421101)
• Refactor val(): don’t strip carriage return, isolate IE workarounds (ff281991)
• Don’t set the type attr hook at all outside of IE (9e66fe9a)

CSS

• Fix dimensions of table <col> elements (#5628, eca2a564)
• Drop the cache in finalPropName (640d5825)
• Tests: Fix tests & support tests under CSS Zoom (#5489, 071f6dba)
• Fix reliableTrDimensions support test for initially hidden iframes (b1e66a5f)
• Selector: Align with 3.x, remove the outer selector.js wrapper (53cf7244)
• Make the reliableTrDimensions support test work with Bootstrap CSS (#5270, 65b85031)
• Make offsetHeight( true ), etc. include negative margins (#3982, bce13b72)
• Return undefined for whitespace-only CSS variable values (#5120) (7eb00196)
• Don’t trim whitespace of undefined custom property (#5105, ed306c02)
• Skip falsy values in addClass( array ), compress code (#4998, a338b407)
• Justify use of rtrim on CSS property values (655c0ed5)
• Trim whitespace surrounding CSS Custom Properties values (#4926, efadfe99)
• Include show, hide & toggle methods in the jQuery slim build (297d18dd)
• Remove the opacity CSS hook (865469f5)
• Workaround buggy getComputedStyle on table rows in IE/Edge (#4490, 26415e08)
• Don’t automatically add “px” to properties with a few exceptions (#2795, 00a9c2e5)

Core

• Remove obsolete workarounds, update support comments (e2fe97b7)
• Switch $.parseHTML from document.implementation to DOMParser (0e123509)
• Fix the exports setup to make bundlers work with ESM & CommonJS (#5416, 60f11b58)
• Add more info about named exports (5f869590)
• Simplify code post browser support reduction (93ca49e6)
• Move the factory to separate exports (46f6e3da)
• Use named exports in src/ (#5262, f75daab0)
• Fix regression in jQuery.text() on HTMLDocument objects (#5264, a75d6b52)
• Selector: Move jQuery.contains from the selector to the core module (024d8719)
• Drop the root parameter of jQuery.fn.init (d2436df3)
• Don’t rely on splice being present on input (9c6f64c7)
• Manipulation: Add basic TrustedHTML support (#4409, de5398a6)
• Report browser errors in parseXML (#4784, 89697325)
• Make jQuery.isXMLDoc accept falsy input (#4782, fd421097)
• Drop support for Edge Legacy (i.e. non-Chromium Microsoft Edge) (#4568, e35fb62d)
• Fire iframe script in its context, add doc param in globalEval (#4518, 4592595b)
• Exclude callbacks & deferred modules in the slim build as well (fbc44f52)
• Migrate from AMD to ES modules 🎉 (d0ce00cd)
• Use Array.prototype.flat where supported (#4320, 9df4f1de)
• Remove private copies of push, sort & splice from the jQuery prototype (b59107f5)
• Implement .even() & .odd() to replace POS :even & :odd (78420d42)
• Deprecate jQuery.trim (#4363, 5ea59460)
• Remove IE-specific support tests, rely on document.documentMode (#4386, 3527a384)
• Drop support for IE <11, iOS <11, Firefox <65, Android Browser & PhantomJS (#3950, #4299, cf84696f)
• Remove deprecated jQuery APIs (#4056, 58f0c00b)

Data

• Refactor to reduce size (805cdb43)
• Event:Manipulation: Prevent collisions with Object.prototype (#3256, 9d76c0b1)
• Separate data & css/effects camelCase implementations (#3355, 8fae2120)

Deferred

• Rename getStackHook to getErrorHook (#5201, 258ca1ec)
• Respect source maps in jQuery.Deferred.exceptionHook (#3179, 0b9c5037)
• Rename master to primary (a32cf632)

Deprecated

• Define .hover() using non-deprecated methods (fd6ffc5e)
• Remove jQuery.trim (0b676ae1)
• Fix AMD parameter order (f810080e)

Dimensions

• Add offset prop fallback to FF for unreliable TR dimensions (#4529, 3bbbc111)

Docs

• Fix some minor issues in comments (e4d4dd81)
• update herodevs link in README (#5695, 093e63f9)
• Align CONTRIBUTING.md with 3.x-stable (d9281061)
• Update CONTRIBUTING.md (4ef25b0d)
• add version support section to README (cbc2bc1f)
• Update remaining HTTP URLs to HTTPS (7cdd8374)
• Fix module links in the package README (ace646f6)
• update watch task in CONTRIBUTING.md (77d6ad71)
• Fix typos found by codespell (620870a1)
• remove stale gitter badge from readme (67cb1af7)
• Remove the “Grunt build” section from the PR template (988a5684)
• Remove stale badge from README (bcd9c2bc)
• Update the README of the published package (edccabf1)
• Remove git.io from a GitHub Actions comment (016872ff)
• Update webpack website in README (01819bc3)
• add link to patchwelcome and help wanted issues (924b7ce8)
• add link to preview the new CLAs (683ceb8f)
• Fix incorrect trac-NUMBER references (eb9ceb2f)
• remove expired links from old jquery source (#4997) (ed066ac7)
• Remove links to Web Archive from source (#4981, e24f2dcf)
• Replace #NUMBER Trac issue references with trac-NUMBER (5d5ea015)
• Update the URL to the latest jQuery build in CONTRIBUTING.md (9bdb16cd)
• Remove the CLA checkbox in the pull request template (e1248931)
• update irc to Libera and fix LAMP dead link (175db73e)
• Update Frequently Reported Issues in the GitHub issue template (7a6fae6a)
• Change JS Foundation mentions to OpenJS Foundation (11611967)
• add SECURITY.md, show security email address (2ffe54ca)
• Fix typos (1a7332ce)
• Update the link to the jsdom repository (a62309e0)
• Use https for hyperlinks in README (73415da2)
• Remove a mention of the event/alias.js module from README (3edfa1bc)
• Update links to EdgeHTML issues to go through Web Archive (1dad1185)
• direct users to GitHub docs for cloning the repo (f1c16de2)
• Change OS X to macOS in README (5a3e0664)
• Update most URLs to HTTPS (f09d9210)
• Convert link to Homebrew from HTTP to HTTPS (e0022f23)

Effect

• Fix a unnecessary conditional statement in .stop() (#4374, 110802c7)

Effects

• Remove jQuery.fx.interval (6c2c7362)

Event

• Use .preventDefault() in beforeunload (7c123dec)
• Increase robustness of an inner native event in leverageNative (#5459, 527fb3dc)
• Avoid collisions between jQuery.event.special & Object.prototype (bcaeb000)
• Simplify the check for saved data in leverageNative (dfe212d5)
• Make trigger(focus/blur/click) work with native handlers (#5015, 6ad3651d)
• Simulate focus/blur in IE via focusin/focusout (#4856, #4859, #4950, ce60d318)
• Don’t break focus triggering after .on(focus).off(focus) (#4867, e539bac7)
• Make focus re-triggering not focus the original element back (#4382, dbcffb39)
• Don’t crash if an element is removed on blur (#4417, 5c2d0870)
• Remove the event.which shim (#3235, 1a5fff4c)
• remove jQuery.event.global (18db8717)
• Only attach events to objects that accept data — for real (#4397, d5c505e3)
• Stop shimming focusin & focusout events (#4300, 8a741376)
• Prevent leverageNative from registering duplicate dummy handlers (eb6c0a7c)
• Fix handling of multiple async focus events (#4350, ddfa8376)

Manipulation

• Make jQuery.cleanData not skip elements during cleanup (#5214, 3cad5c43)
• Generalize a test to support IE (88690ebf)
• Support $el.html(selfRemovingScript) (#5378) (#5377, 937923d9)
• Extract domManip to a separate file (ee6e8740)
• Don’t remove HTML comments from scripts (#4904, 2f8f39e4)
• Respect script crossorigin attribute in DOM manipulation (#4542, 15ae3614)
• Avoid concatenating strings in buildFragment (9c98e4e8)
• Make jQuery.htmlPrefilter an identity function (90fed4b4)
• Selector: Use the nodeName util where possible to save size (4504fc3d)

Offset

• Increase search depth when finding the ‘real’ offset parent (556eaf4a)

Release

• 4.0.0 (4f2fae08)
• remove dist files from main branch (c838cfb5)
• 4.0.0-rc.2 (97525193)
• Update AUTHORS.txt (c128d5d8)
• Fix release issues uncovered during the 4.0.0-rc.1 release (a5b0c431)
• remove dist files from main branch (9d06c6dd)
• 4.0.0-rc.1 (586182f3)
• Run npm publish in the post-release phase (ff1f0eaa)
• Only run browserless tests during the release (fb5ab0f5)
• Temporarily disable running tests on release (3f79644b)
• publish tmp/release/dist folder when releasing (#5658, a865212d)
• correct build date in verification; other improvements (53ad94f3)
• remove dist files from main branch (be048a02)
• 4.0.0-beta.2 (51fffe9f)
• ensure builds have the proper version (3e612aee)
• set preReleaseBase in config file (1fa8df5d)
• fix running pre/post release scripts in windows (5518b2da)
• update AUTHORS.txt (862e7a18)
• migrate release process to release-it (jquery/jquery-release#114, 2646a8b0)
• add factory files to release distribution (#5411, 1a324b07)
• use buildDefaultFiles directly and pass version (b507c864)
• copy dist-module folder as well (63767650)
• only published versioned files to cdn (3a0ca684)
• remove scripts and dev deps from dist package.json (7eac932d)
• update build command in Release.generateArtifacts (3b963a21)
• add support for md5 sums in windows (f088c366)
• remove the need to install grunt globally (b2bbaa36)
• upgrade release dependencies (967af732)
• Remove an unused chalk dependency (bfb6897c)
• Use an in-repository dist README fixture (358b769a)
• Update AUTHORS.txt (1b74660f)
• update AUTHORS.txt (cf9fe0f6)

Selector

• Remove the workaround for :has; test both on iPhone & iPad (65e35450)
• Properly deprecate jQuery.expr[ ":" ]/jQuery.expr.filters (329661fd)
• Make selector.js module depend on attributes/attr.js (#5379, e06ff088)
• Eliminate selector.js depenencies from various modules (e8b7db4b)
• Re-expose jQuery.find.{tokenize,select,compile,setDocument} (#5259, 338de359)
• Stop relying on CSS.supports( “selector(…)” ) (#5194, 68aa2ef7)
• Backport jQuery selection context logic to selector-native (#5185, 2e644e84)
• Make selector lists work with qSA again (#5177, 09d988b7)
• Implement the uniqueSort chainable method (#5166, 5266f23c)
• Re-introduce selector-native.js (4c1171f2)
• Manipulation: Fix DOM manip within template contents (#5147, 3299236c)
• Drop support for legacy pseudos, test custom pseudos (8c7da22c)
• Use jQuery :has if CSS.supports(selector(...)) non-compliant (#5098, d153c375)
• Remove the “a:enabled” workaround for Chrome <=77 (c1ee33ad)
• Make empty attribute selectors work in IE again (#4435, 05184cc4)
• Use shallow document comparisons in uniqueSort (#4441, 15750b0a)
• Add a test for throwing on post-comma invalid selectors (6eee5f7f)
• Make selectors with leading combinators use qSA again (ed66d5a2)
• Use shallow document comparisons to avoid IE/Edge crashes (#4441, aa6344ba)
• reduce size, simplify setDocument (29a9544a)
• Leverage the :scope pseudo-class where possible (#4453, df6a7f7f)
• Bring back querySelectorAll shortcut usage (cef4b731)
• Inline Sizzle into the selector module (47835965)
• Port Sizzle tests to jQuery (79b74e04)

Support

• ensure display is set to block for the support div (#4832, 09f25436)

Traversing

• Fix contents() on <object>s with children in IE (ccbd6b93)
• Fix contents() on <object>s with children (#4384, 4d865d96)

20 lat jQuery i ludzie za kulisami

W ogłoszeniu przewija się też wątek jubileuszu: część społeczności spotkała się na reunionie w Dallas, a John Resig dołączył zdalnie przez Zoom. Release został opublikowany, gdy wszyscy byli razem.

Autorzy podziękowali wszystkim osobom, które dołożyły się do wydania: Alex, Ahmed S. El-Afifi, fecore1, Dallas Fraser, Richard Gibson, Michał Gołębiowski-Owczarek, Pierre Grimaud, Gabriela Gutierrez, Jonathan, Necmettin Karakaya, Anders Kaseorg, Wonseop Kim, Simon Legner, Shashanka Nataraj, Pat O’Callaghan, Christian Oliff, Dimitri Papadopoulos Orfanos, Wonhyoung Park, Bruno PIERRE, Baoshuo Ren, Beatriz Rezener, Sean Robinson, Ed Sanders, Timo Tijhof, Tom, Christian Wenz, ygj6 oraz całemu zespołowi jQuery.

Podsumowanie: na co zwrócić uwagę przy aktualizacji

• Jeśli wspierasz IE10 i starsze lub bardzo stare przeglądarki (Edge Legacy, Android Browser itp.) – jQuery 4.0 nie jest dla ciebie; zostaje 3.x.
• Jeśli masz rygorystyczne CSP, zwróć uwagę na zmiany wokół <script> transportu i Trusted Types/TrustedHTML.
• W kodzie usuń użycia zdeprecjonowanych funkcji (np. jQuery.trim, jQuery.parseJSON) na rzecz natywnych odpowiedników.
• Nie polegaj na push/sort/splice na obiekcie jQuery – te metody zostały wycięte z prototypu.
• Sprawdź logikę opartą o focus/blur – zmieniła się kolejność eventów zgodnie z aktualnym W3C.
• Rozważ slim build, jeśli i tak nie używasz AJAX/Deferred/Callbacks, ale pamiętaj o IE11 (brak natywnych Promise).