Přeskočit na obsah
Všechny články
Web a vývoj

Payload 4: Co zkontrolovat před upgradem z verze 3

Payload 4 vyžaduje Node.js 24.22.3+, Next.js 16.4.1+ a u SQL databází migraci. Co zkontrolovat před upgradem z verze 3 a proč Node.js aktualizovat už teď.

Payload 4 – co zkontrolovat před upgradem z verze 3, od Node.js po databázi

Payload 4 je zatím v betě, ale už teď je jasné, co bude potřebovat: Node.js 24 nebo 26, novější Next.js a u SQL databází migraci. Jenže nejdůležitější krok se netýká Payloadu. Aktualizaci Node.js byste neměli odkládat, i kdyby upgrade CMS čekal ještě půl roku.

Když jsem přecházel z WordPressu na Payload, jedním z hlavních důvodů byla kontrola. Méně pluginů, čistší kód, méně překvapení po aktualizaci.

Ta kontrola má ale i druhou stranu. Za upgrade odpovídáte vy, ne tlačítko „Aktualizovat vše“ v administraci.

A velký upgrade se blíží. Payload 4 je od října v betě a 13. listopadu vyšla beta 9. Ta přinesla dvě změny, které stojí za pozornost i u webů, které na verzi 4 zatím nepřejdou.

Co se v betě 9 změnilo?

1. Minimální verze Node.js. Payload 4 teď vyžaduje ^24.22.3 || >=26.13.1. Prakticky:

  • Node.js 22 — nepodporovaný.
  • Node.js 24 — jen od verze 24.22.3.
  • Node.js 25 — nepodporovaný.
  • Node.js 26 — od verze 26.13.1.

Release notes to říkají jasně: aplikace na starších verzích musí aktualizovat runtime lokálně, v CI i v nasazení.

2. Migrace tabulek sessions. U SQL adaptérů přibyly v tabulkách <kolekce>_sessions tři nové sloupce. Existující projekty proto potřebují migraci databáze. U MongoDB není potřeba nic.

Obojí vypadá jako drobnost. Ale to první má dopad i na weby, které na Payload 4 nepřejdou ještě dlouho.

Proč zrovna tyhle verze Node.js?

Verze 24.22.3 a 26.13.1 nejsou náhodné. Jsou to opravená vydání z bezpečnostní aktualizace Node.js z 11. listopadu 2026. Spolu s nimi vyšla i verze 22.23.5.

Oprava řeší 16 zranitelností: sedm s vysokou závažností, šest se střední a tři s nízkou. Většina se týká HTTP/2 a TLS.

Nejzajímavější je podle mě CVE-2026-123864. Za určitých podmínek umožňuje nepřihlášenému klientovi přečíst paměť, která patří jiným spojením. Podle Node.js v ní mohou být i soukromé klíče TLS nebo požadavky jiných uživatelů. Týká se verzí 22, 24 i 26.

Podmínky jsou poměrně specifické. Týká se to HTTPS v Node.js, čisté HTTP (node:http) zasažené není. Handler musí odeslat hlavičky dřív, než dorazí celé tělo požadavku. K přečtení uniklé paměti pak útočník potřebuje běžnou cestu, která tělo požadavku vrací nebo ukládá. Spousta webů tyhle podmínky nejspíš nesplní. Já bych ale nerad u každého projektu zvlášť dokazoval, že zrovna ten je nesplňuje. Aktualizace je jednodušší.

Payload tu jde stejnou cestou jako u verze 3.92.0 z října. Tehdy zvedl minimum na opravené vydání Node.js 22. Teď u verze 4 udělal totéž s listopadovými opravami.

Proč s Node.js nečekat na Payload 4?

Tady se podle mě vyplatí trochu zpomalit. Jde totiž o tři různé věci, které se snadno slijí do jedné.

Bezpečnostní patch Node.js se týká vás už dnes. Payload 3 (aktuálně 3.93.0) podporuje ^22.23.4 || >=24.22.1. Na Node.js 22.23.5 nebo 24.22.3 tedy poběží bez problémů. Nemusíte čekat na nic.

Přechod z Node.js 22 na 24 vás čeká tak jako tak. Podpora Node.js 22 končí 30. dubna 2027. Node.js 24 má podporu do dubna 2028 a Node.js 26 je od 28. října 2026 aktivní LTS s podporou do dubna 2029.

Payload 4 je zatím beta. Termín stabilní verze jsem v oficiálních zdrojích nenašel. Na npm je pod značkou latest pořád Payload 3.93.0.

Takže doporučuji tři samostatné kroky místo jednoho velkého:

  1. Teď: patch Node.js na 22.23.5, 24.22.3 nebo 26.13.1.
  2. V klidu, ještě na Payloadu 3: přechod z Node.js 22 na 24 (nebo 26). Otestovat, nasadit, nechat chvíli běžet.
  3. Až bude Payload 4 stabilní: samotný upgrade CMS.

Checklist 1: Runtime všude, kde web žije

Verze Node.js není jedno nastavení. Je jich obvykle pět a stačí, aby jedno zůstalo pozadu.

  • Lokální vývoj: .nvmrc nebo .node-version v repozitáři.
  • package.json: pole engines. Payload v betě 9 sám používá:
"engines": {
  "node": "^24.22.3 || >=26.13.1"
}
  • CI: třeba node-version v actions/setup-node u GitHub Actions. Tady stará verze přežívá nejčastěji.
  • Docker: základní image ve Dockerfile, například FROM node:24-alpine. Po aktualizaci image znovu sestavte, starý se sám neobnoví.
  • Hosting: na Vercelu nastavení Node.js Version v projektu (pozor, engines v package.json ho přepíše). Na vlastním serveru node -v a kontrola, že PM2 nebo systemd používá stejnou verzi.
  • Vedlejší procesy: cron, workery pro jobs, skripty pro migrace a seedování. Na ty se zapomíná nejčastěji.

Checklist 2: Závislosti a stav projektu

Payload 4 nezvedá jen Node.js. Podle migračního průvodce potřebuje také:

  • Next.js 16.4.1 nebo novější v rámci řady 16.
  • React a React DOM ^19.3.1.
  • TypeScript 6.0.3 nebo novější.
  • Lexical místo Slate. Editor Slate ve verzi 4 úplně skončil. Pokud ho máte, zůstaňte na Payloadu 3 a nejdřív převeďte obsah do Lexicalu.
  • Starý obsah z bet verze 3. Pokud databáze může obsahovat rich text z dob bet Payloadu 3, je potřeba ještě na verzi 3 spustit upgradeLexicalData.
  • Pluginy a vlastní komponenty v administraci. Projděte, které používáte. Některé změny se týkají právě jich.

Checklist 3: Databáze

Tady se cesty rozcházejí podle toho, na čem web běží.

MongoDB: pro nová pole migraci nepotřebujete.

Postgres, SQLite a D1: po upgradu vygenerujte migraci, zkontrolujte ji a spusťte:

payload migrate:create
payload migrate

Ve vývoji se schéma upraví automaticky. V produkci ne.

Migrace přitom nebude jen o sessions. Payload 4 má nově verze dokumentů zapnuté ve výchozím stavu (u každé kolekce bez nastavení versions přibude tabulka _versions) a také sledování autorství (createdBy a updatedBy). Obojí znamená změny ve schématu.

Pokud chcete schéma zatím nechat beze změn, existují codemody migrate-versions-default a migrate-authorship-default. Doplní do konfigurace versions: false a authorship: false tam, kde nastavení chybí. Pluginy, které vkládají vlastní kolekce, ale nepokryjí.

  • Záloha produkční databáze před migrací. A ověřené, že se z ní dá obnovit.
  • Migrace nejdřív na kopii produkčních dat, ne na prázdné databázi.
  • Rozhodnutí, jestli verze a autorství chcete, nebo je zatím vypnete.

Checklist 4: Codemod

Payload k upgradu dodává nástroj, který většinu změn v kódu udělá sám:

npx @payloadcms/codemod

Podle dokumentace je idempotentní a dá se bezpečně spustit i na napůl převedeném projektu. Existuje i varianta s AI asistencí (npx @payloadcms/codemod@beta upgrade).

Codemod šetří hodně ruční práce. Neznamená to ale, že po něm stačí jen nasadit.

  • Spouštějte ho v samostatné větvi a projděte celý diff.
  • Po něm spusťte typecheck. Dokumentace sama uvádí případy, které codemod nevyřeší, třeba volání s rozbalenými argumenty (payload.find({ ...args })).
  • Zvlášť si projděte změny kolem overrideAccess. To je změna, kterou bych sám hlídal nejvíc.

Proč? V Payloadu 4 se u Local API ve výchozím stavu uplatňují přístupová práva. Ve verzi 3 se přeskakovala. Volání, které overrideAccess neuvádí, se dál zkompiluje bez chyby. Jen se začne chovat jinak.

Codemod proto doplní overrideAccess: true všude, kde zachová původní chování. To je bezpečné pro kompatibilitu, ale ne vždy správné. Kde operace běží jménem přihlášeného uživatele, je podle dokumentace bezpečnější volbou nové výchozí chování.

Checklist 5: Co otestovat

Po upgradu bych prošel minimálně:

  • Přihlášení a odhlášení do administrace i na frontendu, pokud ho web má.
  • Přístupová práva: co vidí a smí editor, co administrátor a co nepřihlášený návštěvník.
  • Data na frontendu. Výchozí hloubka dotazů klesla ze dvou úrovní vztahů na jednu. Stránka, která počítala s vnořenými daty, může najednou zobrazit jen ID. Řešením je depth: 2 u konkrétních dotazů, nebo defaultDepth: 2 v konfiguraci.
  • Rich text: vykreslení obsahu z Lexicalu, hlavně pokud jste používali starší HTML konvertory. Ty ve verzi 4 skončily.
  • Nahrávání souborů a úložiště. Storage adaptéry se přesunuly do hlavní konfigurace.
  • Jobs a plánované úlohy. I u nich se teď ve výchozím stavu kontrolují přístupová práva.
  • Vlastní komponenty v administraci. Administrace prošla redesignem.
  • Logy po nasazení. První den po upgradu se vyplatí sledovat.

Kdy na Payload 4 přejít?

Rozhodnutí podle mě není ideologické. Záleží na projektu.

Dává smysl začít zkoušet už teď, když máte vlastní testovací prostředí a chcete vědět, kolik práce upgrade obnáší. Beta je na tohle ideální. Ukáže, co se rozbije, bez tlaku na termín.

Dává smysl počkat na stabilní verzi u webu, který denně používá redakce nebo obchod. Beta se pořád mění, mezi betou 8 a 9 se změnily požadavky na runtime i schéma databáze. Payload 3 dál dostává opravy a je to stabilní volba.

V obou případech platí totéž: Node.js aktualizujte hned.

Závěr

Payload 4 přinese hodně dobrého — redesign administrace, nové výchozí chování a lepší nástroje pro upgrade. Upgrade ale nebude „za pět minut“. A neměl by být ani jeden velký krok.

Nejdřív runtime. Pak databáze a kód. Nakonec testy. Každý krok zvlášť, aby bylo jasné, co co způsobilo.

A bezpečnostní patch Node.js? Ten na Payload 4 nečeká. Týká se vašeho webu už dnes.

Máte web na Payloadu 3 a nevíte, jak daleko je od verze 4? Napište mi. Projdu runtime, databázi i kód, sepíšu, co upgrade obnáší, a navrhnu postup po krocích, který nezastaví provoz webu. Jak řeším hosting a provoz, najdete na webu, případně můžete rovnou vyplnit nezávazný brief.

Zdroje: Payload CMS — v4.0.0-beta.9 release notes (13. 11. 2026); 3.0 to 4.0 Migration Guide; v4.0.0-beta.0 release notes (codemod); Payload 4.0 Beta. Node.js — November 2026 Security Releases; release schedule.

Máte projekt, o kterém by se dal napsat další článek?

Napište nezávazný brief — projdeme cíle, stack i další krok. Bez tlaku a bez závazku.

  • Weby a digitální produkty
  • Identita a webdesign
  • Konzultace i dlouhodobá správa