Node.js 26 upgrade playbook: що перевірити перед апгрейдом

Node.js 26 вийшов у травні 2026 — і 26.1.0 вже на підході. Якщо ти тримаєш проєкт на Node 22 або 24, є кілька місць, які реально можуть зламатися, якщо їх не перевірити заздалегідь.

Що змінилося

Node.js 26 приніс три великі зміни, які безпосередньо торкнуться твого коду:

1. Temporal API ввімкнено за замовчуванням

Нарешті сучасна робота з датами і часом. Забуваємо про старий Date з його дивними багами та незручним API. Тепер Temporal — частина стандартного рантайма.

2. Видалено старі API

Кілька legacy-методів пішли назавжди. Найпомітніше — writeHeader(), який давно замінили на writeHead(), і модулі _stream_* з legacy-префіксом.

3. Runtime deprecation warnings

Багато попереджень тепер видимі в рантаймі за замовчуванням. Це означає, що твій CI може раптово стати набагато “голоснішим”, а в production з’являться нові warning-и в логах.

Чому це важливо

Навіть якщо команда не біжить одразу за Current-релізами, Node.js 26 скоро стане LTS. І тоді апгрейд буде не “хочу”, а “треба”.

Ось що може піти не так, якщо просто оновити версію без перевірки:

• CI починає сипати помилками через нові deprecation warnings
• Legacy API викликає падіння в production, бо методи видалені
• Temporal змінює поведінку date/time логіки, якщо код покладався на специфіку старого Date API
• Залежності ламаються, якщо вони використовують видалені методи Node.js

Як діяти: покроковий плейбук

Ось конкретний порядок дій, який займе 30–40 хвилин:

Крок 1. Перевір залежності від видалених API

Шукаємо в коді:

# Шукаємо writeHeader
grep -r "writeHeader" --include="*.js" --include="*.ts" src/

# Шукаємо legacy stream модулі
grep -r "_stream_" --include="*.js" --include="*.ts" src/

Якщо знайшов — заміни перед апгрейдом:

// Було (Node 22/24, тепер видалено)
res.writeHeader(200)

// Треба (Node 26)
res.writeHead(200)

// Було (legacy)
const stream = require('_stream_readable')

// Треба (Node 26)
const { Readable } = require('stream')

Крок 2. Підготуй код до Temporal

Temporal — це принципово новий підхід до дат і часу:

// Стара школа (Node 22/24)
const now = new Date()
const tomorrow = new Date(now.getTime() + 24 * 60 * 60 * 1000)

// Node 26 з Temporal
const now = Temporal.Now.instant()
const tomorrow = now.add({ days: 1 })

Не роби цього: не переписуй одразу всю date/time логіку на Temporal. Краще зроби це: перевір, чи твій код не ламається з увімкненим Temporal, і почни поступово мігрувати критичні місця.

Крок 3. Протестуй CI з новими warnings

Запусти тестовий набір з прапорцями, щоб побачити всі попередження:

node --trace-warnings your-script.js

Це покаже, скільки шуму з’явиться в CI після апгрейду. Якщо warnings сипляться сотнями — треба фіксити код до деплою.

Крок 4. Оновлюй на staging, не на production

Стандартна процедура:

1. Постав Node.js 26 на staging
2. Запусти всі тести: unit, integration, smoke
3. Перевір CLI-скрипти та build pipeline
4. Подивись на логи — чи з’явилися нові warning-и
5. Виміряй cold start і порівняй з Node 24

Тільки якщо все пройшло — рухай далі.

Крок 5. Підготуй rollback

Завжди май план відкату:

# Фіксуємо поточну версію
node -v > .node-version

# Для nvm користувачів
nvm install 24  # або поточну LTS версію
nvm use 24

Зроби цей крок до апгрейду, а не після того, як щось зламалося.

Типові помилки

• Апгрейд без тестів. “Воно ж має працювати” — ні, не має
• Ігнорування warnings. Сьогодні warning, завтра падіння. API видаляють не одразу, але видаляють
• Переписування всього на Temporal одразу. Це шлях до багів. Мігруй поступово
• Тестування тільки сервера. CLI-скрипти, build tools і CI ламаються першими
• Забування про залежності. Перевір, чи твої npm-пакети підтримують Node 26
• Плутанина між Current і LTS. Node 26 — Current реліз, не LTS. LTS прийде пізніше

Висновок

Node.js 26 — це потужний реліз з Temporal, V8 14.6, Undici 8 і багатьма іншими покращеннями. Але перш ніж оновлювати production, пройди цей чек-лист.

Швидкий план дій:

1. Знайди використання видалених API
2. Підготуй код до Temporal (поступово)
3. Протестуй CI з warnings
4. Оновлюй на staging
5. Май готовий rollback

Не поспішай, але й не відкладай. LTS прийде — і тоді доведеться апгрейдитися.

Офіційні джерела:

• https://nodejs.org/en/blog/release/v26.0.0
• https://nodejs.org/en/blog/release/v26.1.0
• https://nodejs.org/api/deprecations.html
• https://nodejs.org/api/http.html#responsewriteheadstatuscode-statusmessage-headers
• https://nodejs.org/api/module.html#moduleregisterspecifier-parenturl-options