NestJS 12 перейшов на ESM-пакети, Standard Schema та native observability

NestJS 12 переводить основні пакети на ESM, додає першу класну підтримку Standard Schema, перебудовує CLI та вводить офіційний SDK спостережуваності @nestjs/observe. Важливий нюанс: власний застосунок не обов’язково переводити з CommonJS. Сучасний Node.js уміє завантажувати ESM-пакети через require(esm), але мінімальні версії runtime та CLI тепер різняться, і саме це може стати головною причиною невдалого оновлення.

ESM у пакетах, але не обов’язково у вашому коді

Core-пакети Nest 12 постачаються як ESM. CommonJS-застосунок може залишитися CommonJS, якщо працює на Node.js із неекспериментальною підтримкою require(esm): офіційний guide називає мінімум Node 20.19 або 22.12. Непарна гілка 21 не підтримується. Команда nest upgrade перевіряє runtime і відмовляється продовжувати на непридатній версії.

Для schematics вимоги вищі через Angular devkit: потрібні Node 22.22.3+, 24.15+ або 26+. Отже, сервер може запускати застосунок на Node 20.19, але цей самий образ не обов’язково зможе генерувати код чи виконати upgrade. Найпростіша політика — активна LTS у CI та окреме документування runtime production.

Новий nest new пропонує CommonJS або ESM layout. Для ESM-проєктів типовим тестовим стеком стає Vitest, а нові проєкти отримують oxlint. Це лише defaults генератора: існуючий Jest та ESLint не потрібно міняти в межах одного migration.

Standard Schema для вхідних і вихідних даних

Декоратори @Body(), @Query(), @Param() і @RawBody() отримали параметр schema. Метадані сумісні з екосистемою Standard Schema — Zod, Valibot, ArkType та іншими бібліотеками. Для виконання перевірки потрібно підключити StandardSchemaValidationPipe; сам декоратор лише зберігає метадані.

StandardSchemaSerializerInterceptor застосовує схему до відповіді, а ті самі описи можуть живити OpenAPI. Декораторний шлях із ValidationPipe, class-validator і ClassSerializerInterceptor залишається підтриманим. Не варто змішувати обидві моделі без правил: інакше вхід може пройти одну схему, а документація або serializer — іншу.

@nestjs/config теж переходить від Joi-специфічного контракту до Standard Schema. Проєктам, які залишають Joi, потрібна версія 18 або новіша. Перед production слід окремо перевірити перетворення типів, default values та формат validation errors.

CLI, збірка й діагностика маршрутів

Оновлення виконується новою командою nest upgrade; усі пакети Nest потрібно переводити на одну major-версію. У monorepo Rspack стає типовим bundler, а webpack-орієнтовані CLI flags позначено deprecated. Підтримано package manager Bun і додано команду deploy, яка інтегрується з окремим інструментом Mau.

Для конфліктів маршрутів з’явилися opt-in diagnostics. В Express параметричний @Get(':id') може перекрити статичний @Get('me'), якщо оголошений раніше. Діагностика допомагає знайти це до того, як помилка проявиться як неправильний handler. Додано також machine-readable error codes і структуровані logging parameters.

Спостережуваність на рівні Nest

Офіційний @nestjs/observe підключається через application option instrument і бачить контролери, providers, resolvers, jobs та queue consumers. Це дає предметніші traces, ніж generic APM hook для Node HTTP. Але новий SDK не скасовує політику приватності: attributes не повинні містити токени, повні request bodies або персональні дані.

Практичний висновок: спочатку оновіть глобальний CLI, потім локальну dev dependency і лише після цього запускайте nest upgrade. Збережіть lock-файл і порівнюйте зміни пакетів окремим pull request.

Що протестувати

• Запуск CommonJS-застосунку з ESM-пакетами на точній production-версії Node.
• CLI, schematics, Jest або Vitest і custom webpack/Rspack configuration.
• Standard Schema для body, query, config та вихідних DTO, включно з форматом помилок.
• NATS serializers, GraphQL subscriptions і порядок lifecycle hooks, якщо вони використовуються.
• Graceful shutdown Express із незавершеними запитами та нову observability instrumentation.

Джерело та права

Матеріал є самостійним українським перекладом-переказом release notes NestJS 12.0.0 та офіційного migration guide 11 → 12. Матеріали обох офіційних репозиторіїв поширюються за MIT License. Реліз опубліковано 27 серпня 2026 року командою NestJS. Перекладено, адаптовано й доповнено редакцією «Бібліотеки програміста». Обкладинка створена редакцією за допомогою AI і не входить до першоджерела.