jQuery 4.0.0: o que muda na primeira major em quase 10 anos (e como atualizar com segurança)

No dia 14 de janeiro de 2006, o John Resig apresentou em Nova Iorque uma biblioteca JavaScript chamada jQuery. Vinte anos depois, o projeto celebra a data com o lançamento final do jQuery 4.0.0 – a primeira major release em quase uma década, depois de um ciclo longo de desenvolvimento e várias pré-releases.

Este 4.0.0 vem com melhorias e modernizações bem alinhadas com o que a web pede hoje: menos código legado, mais compatibilidade com práticas de segurança atuais (como CSP e Trusted Types), e uma base preparada para ferramentas modernas de build. Ao mesmo tempo, é uma versão com breaking changes, então faz sentido ler os pontos críticos antes de trocar o 3.x no teu projeto.

Para ajudar na migração, o time disponibilizou um upgrade guide e uma nova release do jQuery Migrate plugin (um plugin pensado para detectar e mitigar incompatibilidades ao atualizar). Se encontrares problemas no upgrade, o caminho recomendado é reportar no tracker oficial de issues.

Onde obter o jQuery 4.0.0 (CDN e npm)

O jQuery 4.0.0 já está disponível no CDN oficial do projeto e no npm. Outros CDNs de terceiros tendem a disponibilizar em seguida, mas o calendário deles não é controlado pelo projeto – por isso pode levar alguns dias.

Links diretos no CDN

• https://code.jquery.com/jquery-4.0.0.js
• https://code.jquery.com/jquery-4.0.0.min.js

Instalação via npm

npm install jquery@4.0.0

npm install jquery@4.0.0

Breaking changes e decisões de limpeza: o que o 4.0.0 removeu (e porquê)

A filosofia desta major release é bem clara: fazer mudanças que o time já queria há anos, mas que não cabiam num patch/minor. Isso inclui: remover código legado, cortar APIs previamente deprecated, eliminar parâmetros internos que estavam expostos em funções públicas sem estarem documentados, e abandonar comportamentos “mágicos” que complicavam manutenção e previsibilidade.

Fim do suporte a IE < 11 (e redução de suporte a browsers muito antigos)

O jQuery 4.0 remove suporte ao Internet Explorer 10 e anteriores. Uma dúvida comum é: por que não remover também o IE11? A resposta é que o plano é remover por etapas; o próximo passo está previsto para ser lançado no jQuery 5.0 (há referência explícita a isso num PR do repositório). Por agora, o corte é do código específico para IE antes do 11.

Além do IE<11, também caiu suporte para outros browsers bem antigos: Edge Legacy, iOS anterior às últimas 3 versões, Firefox anterior às últimas 2 versões (com exceção do Firefox ESR) e Android Browser.

Segurança moderna: Trusted Types e CSP (Content Security Policy)

Uma das melhorias mais relevantes do 4.0.0 é o suporte a Trusted Types. Na prática, isso garante que HTML encapsulado em TrustedHTML (a API do browser para reduzir XSS em sinks perigosos) possa ser passado como input para métodos de manipulação do jQuery sem violar a diretiva require-trusted-types-for da Content Security Policy (CSP).

Em paralelo, o time também ajustou o comportamento do Ajax para reduzir erros de CSP: embora alguns requests já usassem tags <script> para manter atributos como crossdomain, agora a maioria dos requests assíncronos de scripts foi alterada para usar <script> tags – evitando problemas típicos quando scripts inline são bloqueados por CSP.

O código-fonte do jQuery migrou para ES modules (adeus AMD no source)

Um marco importante do 4.0.0 é que o código-fonte na branch main foi migrado de AMD (o formato muito associado ao RequireJS) para ES modules (ESM).

Historicamente, o source sempre foi publicado via npm e GitHub, mas não dava para importá-lo diretamente como módulos sem o RequireJS, que era a ferramenta de build escolhida pelo projeto. Agora o empacotamento usa Rollup, e os testes são executados separadamente também em cima dos ES modules.

O resultado prático é que o jQuery fica mais compatível com ferramentas modernas de build, workflows atuais e browsers modernos, inclusive com a opção de consumo via <script type=module>.

APIs deprecated removidas (e o que usar no lugar)

Como é uma major release, foi o momento de remover funções que já vinham marcadas como deprecated há várias versões – muitas delas porque eram pensadas para uso interno, ou porque hoje têm equivalentes nativos em todos os browsers suportados pelo jQuery 4.0.

Lista de funções removidas no 4.0.0:

• 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

As substituições recomendadas passam pelo que já usamos no JavaScript moderno: Array.isArray(), JSON.parse(), String.prototype.trim() e Date.now(), entre outras APIs nativas.

Um detalhe interessante: a combinação da remoção dessas APIs deprecated com a eliminação de código para IE antigo gerou uma redução de mais de 3k bytes (gzipped) no tamanho final.

Métodos internos removidos do prototype do jQuery: push, sort e splice

Durante muito tempo, o prototype do jQuery expôs métodos de Array que não se comportavam como os restantes métodos chainable do jQuery e eram pensados apenas para uso interno. Esses métodos eram: push, sort e splice.

No jQuery 4.0, eles foram removidos do prototype. Se tens algum código que fazia coisas como $elems.push(elem), a alternativa indicada é chamar o método nativo do Array explicitamente via call.

// Antes (3.x):
// $elems.push( elem )

// Depois (4.0):
[].push.call( $elems, elem );

// Antes (3.x):
// $elems.push( elem )

// Depois (4.0):
[].push.call( $elems, elem );

Ordem de eventos de focus/blur agora segue a spec W3C

Este é daqueles breaking changes que costuma passar despercebido até quebrar um fluxo de UI: durante anos, browsers divergiram na ordem de eventos de foco e desfoco (focusin, focusout, focus, blur). Com o tempo, os browsers suportados pelo jQuery 4.0 convergiram para uma ordem comum – mas diferente da ordem “consistente” que o jQuery tinha escolhido no passado.

A partir do jQuery 4.0, o jQuery deixa de sobrescrever o comportamento nativo. Assim, todos os browsers (exceto IE) seguem a especificação atual da W3C, nesta ordem:

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

Nas versões anteriores, a ordem do jQuery era: focusout, blur, focusin, focus. Um detalhe curioso apontado no anúncio: o único browser que seguia a spec antiga (antes da atualização de 2023) era o Internet Explorer.

Slim build atualizado: ainda menor (e sem Deferreds/Callbacks)

O build “slim” no jQuery 4.0.0 encolheu ainda mais: Deferreds e Callbacks foram removidos, ficando por volta de 19.5k bytes gzipped.

A justificativa é prática: Deferreds já suportavam há muito o padrão Promises/A+, então em grande parte dos casos dá para migrar para Promises nativas, que estão disponíveis em todos os browsers suportados pelo jQuery 4.0 – com exceção do IE11.

Deferreds têm alguns recursos extra que as Promises nativas não cobrem, mas a expectativa do projeto é que a maior parte do uso possa ser migrada para métodos de Promise.

Links do slim build

• https://code.jquery.com/jquery-4.0.0.slim.js
• https://code.jquery.com/jquery-4.0.0.slim.min.js

O anúncio também menciona que estas atualizações já estão disponíveis como versões atuais no npm e no Bower, e que há uma página com todas as formas de obter o jQuery em https://jquery.com/download/.

Como atualizar sem dor: upgrade guide, jQuery Migrate e checklist

O time do jQuery publicou dois recursos-chave para atravessar o 3.x → 4.0 com menos fricção: o Upgrade Guide e a release do jQuery Migrate plugin. A expectativa oficial é que a maioria dos projetos consiga atualizar com mudanças mínimas, mas vale tratar o upgrade como uma pequena migração.

1. Lê o guia oficial de upgrade: https://jquery.com/upgrade-guide/4.0/
2. Inclui o jQuery Migrate no ambiente de teste/homologação para detectar padrões quebrados: https://github.com/jquery/jquery-migrate/
3. Valida dependências: plugins e temas (ou bundles antigos) podem depender de APIs removidas como jQuery.trim ou de comportamentos “mágicos”.
4. Revê handlers de focus/blur se tens componentes que dependem da ordem dos eventos (form wizards, máscaras, validação on-focus, etc.).
5. Procura usos de $collection.push/sort/splice e substitui por chamadas explícitas ao Array.
6. Se usas Ajax para carregar scripts, confirma se estás a passar headers nesse transporte; quando aplicável, muda para scriptAttrs conforme a orientação do anúncio.
7. Se a tua política de segurança usa CSP estrita e/ou require-trusted-types-for, testa fluxos de .html(), .append() e afins com Trusted Types no browser alvo.
8. Se precisas mesmo de browsers muito antigos (IE10-, Edge Legacy, Android Browser, etc.), considera manter o jQuery 3.x no produto que os atende.

Se encontrares um bug real ao atualizar, o caminho recomendado é abrir issue em https://github.com/jquery/jquery/issues.

Changelog completo e destaques por área

Para quem gosta de ir ao detalhe, o projeto disponibilizou o diff completo entre 3.7.1 e 4.0.0 aqui: https://github.com/jquery/jquery/compare/3.7.1…4.0.0. A seguir, ficam os itens do changelog organizados por área (conforme publicado).

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 anos de jQuery: o reencontro do time

O anúncio também marca o aniversário de 20 anos do projeto e menciona um reencontro em Dallas com várias pessoas que contribuíram ao longo do tempo – incluindo a participação do John Resig por Zoom. A release foi publicada enquanto estavam juntos.

Resumo do que interessa para quem mantém projetos (incluindo WordPress)

• Se tens dependência de browsers antigos, o recado é direto: jQuery 3.x continua a ser a linha adequada.
• Para ambientes modernos, o 4.0.0 simplifica o core, melhora integração com CSP/Trusted Types e aproxima o projeto das ferramentas atuais com ES modules.
• Os principais pontos de quebra tendem a aparecer em: APIs removidas (ex.: jQuery.trim), ordem de eventos de foco, e usos acidentais de métodos de Array no prototype do jQuery.
• Slim build ficou menor e agora elimina Deferreds/Callbacks – ótimo para quem já está 100% em Promises nativas, mas exige cuidado se ainda existe requisito de IE11.