# Apa yang Berubah di Zod 4: Performa, Mini, dan Migrasi

> Zod 4 menulis ulang inti validasinya demi kecepatan, menambah build mini tree-shakable 1,9 KB, dan mengubah penanganan error — inilah yang berubah dan cara migrasinya.

URL: https://www.matthewswong.com/id/blog/zod-4-schema-validation-performance/

- Author: Matthews Wong (https://www.matthewswong.com/id/about/)
- Published: 2026-07-14
- Updated: 2026-07-14
- Category: Web Dev

> **Key takeaway:** Zod 4 hadir di dalam paket zod utama dan menulis ulang inti validasinya demi kecepatan: parsing string sekitar 14x lebih cepat, array 7x lebih cepat, dan pemangkasan 100x pada instansiasi TypeScript di skema berantai. Ia menambah build zod/mini yang tree-shakable sekitar 1,9 KB gzipped, menyatukan kustomisasi error di bawah satu parameter error, dan memindahkan format string ke fungsi tingkat atas seperti z.email().

Saya mengandalkan Zod di hampir setiap service TypeScript yang saya jalankan: memvalidasi request body di NestJS, mem-parse variabel environment saat boot, dan menjaga JSON yang saya tarik dari API pihak ketiga. Jadi ketika versi mayor rilis dengan sorotan berupa performa, saya menyimak. Zod 4 bukan sekadar pembaruan kosmetik. Intinya ditulis ulang, biaya di level tipe turun drastis, dan beberapa API yang saya pakai setiap hari berubah bentuk.

Berikut apa yang benar-benar berubah, berapa biaya migrasinya, dan di mana build zod/mini baru layak dipakai. Semua di bawah berasal dari pengalaman langsung meng-upgrade, disilangkan dengan catatan rilis resmi Zod 4 dan panduan migrasinya.

## Cerita performanya nyata, dan sebagian besar terjadi saat kompilasi

Angka runtime yang dipublikasikan Zod benar-benar besar: parsing string sekitar 14x lebih cepat, array 7x lebih cepat, dan objek 6,5x lebih cepat dibanding Zod 3. Itu berasal dari meratakan sistem check internal dan membunuh wrapper ZodEffects lama yang dulu membungkus refinement dan transform. Di jalur request panas yang memvalidasi setiap payload, itu berpengaruh.

Tetapi perubahan yang paling saya rasakan adalah yang di level tipe. Zod melaporkan pengurangan hingga 100x pada instansiasi tipe tsc ketika Anda merantai method seperti .extend() dan .omit(). Pada file skema besar, itulah perbedaan antara editor yang mengikuti dan editor yang tersendat. Jika Anda pernah melihat TypeScript tersendat pada skema Zod yang tersusun dalam. peningkatan ini saja sudah bisa membenarkan upgrade.

> Sebelum migrasi, jalankan test suite Anda sekali di Zod 3 dan catat waktu jamnya. Ulangi setelah upgrade. Kemenangan runtime mudah terlihat di test yang berat parsing, dan memberi Anda angka konkret untuk ditaruh di deskripsi pull request alih-alih mengutip benchmark yang tidak Anda jalankan sendiri.

## Kustomisasi error: satu parameter error menggantikan tiga

Ini perubahan breaking yang paling sering Anda temui. Zod 3 punya tiga cara tumpang tindih untuk mengustomisasi pesan: required_error, invalid_type_error, dan errorMap, ditambah message biasa pada refinement. Zod 4 meleburkan semuanya menjadi satu parameter error. Ia menerima string untuk kasus sederhana atau fungsi yang menerima issue untuk logika kondisional. Field message lama masih bekerja tetapi sudah deprecated.

Ada juga error map global sehingga Anda bisa melokalkan pesan di satu tempat, yang sangat berguna ketika Anda melayani pengguna berbahasa Inggris dan Indonesia. Model mentalnya lebih bersih: ada tepat satu tempat untuk mengatur error, dan itu sama di setiap posisi.

## Format string pindah ke fungsi tingkat atas

Di Zod 3 Anda menulis z.string().email(). Di Zod 4 validator format menjadi fungsi tingkat atas: z.email(), z.uuid(), z.url(), z.ipv4(), z.ipv6(). Bentuk method berantai masih ada tetapi deprecated, dan membawa biaya ukuran bundle karena memaksa seluruh mesin format string masuk ke build Anda. Fungsi tingkat atas bersifat tree-shakable, sehingga Anda hanya mengirim validator yang Anda impor.

> z.uuid() lebih ketat di Zod 4 — ia memvalidasi terhadap RFC 9562 dan akan menolak beberapa string yang diterima Zod 3, termasuk nilai mirip UUID non-standar tertentu. Jika Anda memvalidasi ID dari sistem lama, uji dengan data nyata sebelum rilis, atau gunakan z.guid() untuk pencocokan yang lebih longgar.

## Perubahan breaking lain yang layak di-grep

- z.record() kini butuh dua argumen dan menyimpulkan key ekshaustif untuk enum. Record atas enum memberi tipe lengkap, bukan parsial — gunakan z.partialRecord() jika Anda mau perilaku key opsional lama.
- .default() kini berlaku pada tipe output dan memotong parsing ketika input undefined. Perilaku sisi input lama tetap ada sebagai .prefault().
- z.number() menolak Infinity, dan .int() hanya menerima safe integer. Kasus tepi numerik yang lolos diam-diam di Zod 3 kini gagal terang-terangan.
- z.function() bukan lagi skema; ia adalah factory fungsi dengan .implement() dan .implementAsync(). Kode apa pun yang memperlakukannya sebagai skema yang bisa di-parse perlu diubah.
- Merge intersection yang gagal kini melempar Error biasa, bukan ZodError dengan kode issue khusus.

Ada codemod resmi, zod-v3-to-v4, yang menangani rename mekanis seperti migrasi parameter error dan perpindahan format string. Saya tetap membaca setiap diff yang dihasilkannya — codemod hebat pada 90 persen yang membosankan dan berbahaya pada 10 persen yang menarik — tetapi ia benar-benar menghemat waktu saya di codebase besar.

## zod/mini: kapan build 1,9 KB itu sepadan

Zod 4 memperkenalkan entry point kedua, zod/mini, dengan API fungsional yang sepenuhnya tree-shakable. Ukurannya sekitar 1,88 KB gzipped, kira-kira 85 persen lebih kecil dari build inti. Alih-alih merantai method, Anda mengomposisi fungsi, dan itulah yang membuatnya shake dengan baik: validator yang tak terpakai tak pernah sampai ke bundle Anda.

Saya tidak akan memakai zod/mini di backend. Di service Node ukuran bundle tak relevan dan ergonomi chaining Zod inti lebih enak dibaca dan dirawat. Tempat mini layak dipakai adalah edge: fungsi serverless dengan anggaran cold-start, bundle browser di mana setiap kilobyte adalah metrik nyata, dan runtime edge. API-nya berbagi inti yang sama, jadi Anda bisa pakai inti di server dan mini di klien tanpa belajar dua library validasi.

| Pertimbangan | Inti zod | zod/mini |
| --- | --- | --- |
| Impor | import * as z from "zod" | import * as z from "zod/mini" |
| Bundle (gzipped) | Lebih besar, API chaining | ~1,9 KB, tree-shakable |
| Ergonomi | Method chaining, paling mudah dibaca | Komposisi fungsi |
| Paling cocok | Backend Node, server | Edge, serverless, browser |

## Bagaimana saya akan mengurutkan upgrade-nya

1. Naikkan ke zod versi 4 dan biarkan TypeScript memunculkan error tipe — compiler adalah checklist migrasi Anda.
2. Jalankan codemod zod-v3-to-v4, lalu baca setiap diff yang dihasilkannya sebelum commit.
3. Grep required_error, invalid_type_error, dan errorMap lalu migrasikan ke satu parameter error.
4. Cari penggunaan .uuid() dan uji terhadap ID produksi nyata, karena RFC 9562 lebih ketat.
5. Jalankan seluruh test suite, lalu putuskan per target apakah bundle browser atau edge sebaiknya pindah ke zod/mini.

Untuk sebagian besar proyek, migrasinya soal satu sore, bukan seminggu. Perubahan parameter error menyentuh banyak file tetapi bersifat mekanis, codemod mengerjakan sebagian besarnya, dan TypeScript menolak membiarkan Anda selesai selagi ada yang masih rusak. Hasilnya — parsing lebih cepat, type checking yang jauh lebih murah, dan build seukuran edge yang nyata — sepadan dengan diff-nya.

## Sources

- Zod 4 release notes (official)
- Zod 4 migration guide (official)
- InfoQ: Zod v4 Available with Major Performance Improvements and Zod Mini

## Source links

- https://zod.dev/v4
- https://zod.dev/v4/changelog
- https://www.infoq.com/news/2025/08/zod-v4-available/

## FAQ

### Apakah Zod 4 paket terpisah dari Zod 3?

Tidak. Zod 4 hadir di dalam paket zod utama — Anda menginstalnya dengan npm install zod pada versi 4. Build ringan yang baru adalah impor subpath, zod/mini, dari paket yang sama. Tidak ada paket @zod/four terpisah untuk diinstal.

### Seberapa lebih cepat Zod 4 dibanding Zod 3?

Zod mempublikasikan benchmark parsing string sekitar 14x lebih cepat, array 7x lebih cepat, dan objek 6,5x lebih cepat dibanding Zod 3. Sama pentingnya, ia melaporkan pengurangan hingga 100x pada instansiasi tipe TypeScript saat merantai method seperti .extend() dan .omit(), yang mempercepat kompilasi dan responsivitas editor pada file skema besar.

### Apa yang menggantikan required_error dan invalid_type_error di Zod 4?

Satu parameter error terpadu menggantikan required_error, invalid_type_error, dan errorMap. Anda memberikan error sebagai string untuk kasus sederhana, atau sebagai fungsi yang menerima issue dan bisa bercabang berdasarkan apakah input undefined. Field message lama masih bekerja tetapi sudah deprecated.

### Kapan sebaiknya memakai zod/mini alih-alih Zod inti?

Gunakan zod/mini ketika ukuran bundle jadi kendala nyata: bundle browser, fungsi serverless dengan anggaran cold-start, dan runtime edge. Ukurannya sekitar 1,9 KB gzipped dan sepenuhnya tree-shakable. Di backend Node, tetaplah dengan Zod inti — ukuran bundle tak relevan di sana dan API method-chaining lebih mudah dibaca untuk dirawat.

### Apakah ada codemod untuk migrasi dari Zod 3 ke Zod 4?

Ya, ada codemod resmi bernama zod-v3-to-v4 yang menangani rename mekanis seperti migrasi parameter error dan memindahkan format string ke fungsi tingkat atas. Ia menangani sebagian besar pekerjaan, tetapi Anda tetap harus membaca setiap diff yang dihasilkannya, karena codemod andal pada perubahan rutin dan berisiko pada yang tak biasa.

---

- HTML version: https://www.matthewswong.com/id/blog/zod-4-schema-validation-performance/
- English: https://www.matthewswong.com/en/blog/zod-4-schema-validation-performance/
- Site index for agents: https://www.matthewswong.com/llms.txt
- Sitemap: https://www.matthewswong.com/sitemap.xml
- API description (OpenAPI): https://www.matthewswong.com/openapi.json