Next.js uygulamalar\u0131nda URL arama parametreleri (search params) y\u00f6netimi, karma\u015f\u0131kla\u015fmaya e\u011filimli ve \u00e7o\u011fu zaman geli\u015ftiriciler i\u00e7in bir ba\u015f a\u011fr\u0131s\u0131 kayna\u011f\u0131 olabilen bir konudur. Genellikle string olarak gelen bu parametreleri elle ayr\u0131\u015ft\u0131rmak, do\u011fru tiplere d\u00f6n\u00fc\u015ft\u00fcrmek ve uygulama state’i ile senkronize etmek, hem zaman al\u0131c\u0131 hem de hata yapmaya a\u00e7\u0131k bir s\u00fcre\u00e7tir. Neyse ki, E\u011fer siz de Next.js projelerinizde URL’deki sorgu parametrelerinin da\u011f\u0131n\u0131kl\u0131\u011f\u0131yla m\u00fccadele ediyorsan\u0131z, bu makale size arad\u0131\u011f\u0131n\u0131z netli\u011fi ve pratik \u00e7\u00f6z\u00fcmleri sunacak. Kod \u00f6rnekleri, ger\u00e7ek d\u00fcnya senaryolar\u0131 ve ileri d\u00fczey ipu\u00e7lar\u0131 ile Web uygulamalar\u0131n\u0131n dinamik do\u011fas\u0131 gere\u011fi, kullan\u0131c\u0131 etkile\u015fimlerini veya sayfa durumunu URL’ler arac\u0131l\u0131\u011f\u0131yla iletmek yayg\u0131n bir y\u00f6ntemdir. \u00d6zellikle Next.js gibi \u00e7er\u00e7evelerde, bir kullan\u0131c\u0131n\u0131n filtreledi\u011fi bir \u00fcr\u00fcn listesini, g\u00f6r\u00fcnt\u00fcledi\u011fi sayfa numaras\u0131n\u0131 veya uygulad\u0131\u011f\u0131 bir s\u0131ralama se\u00e7ene\u011fini URL’de arama parametreleri ( Bu parametrelerin ilk ve en b\u00fcy\u00fck sorunu, taray\u0131c\u0131 taraf\u0131ndan her zaman bir string olarak i\u015flenmesidir. Sayfa numaras\u0131 ( Next.js’in App Router yap\u0131s\u0131nda veya Pages Router’da kullan\u0131lan Dahas\u0131, karma\u015f\u0131k veri yap\u0131lar\u0131n\u0131 (\u00f6rne\u011fin bir dizi kategori se\u00e7imi veya bir fiyat aral\u0131\u011f\u0131 objesi) URL’de temsil etmek ve bunlar\u0131 g\u00fcvenli bir \u015fekilde ayr\u0131\u015ft\u0131r\u0131p serialize etmek ba\u015fl\u0131 ba\u015f\u0131na bir meydan okumad\u0131r. Geli\u015ftiriciler genellikle bu t\u00fcr durumlar i\u00e7in kendi \u00f6zel hook’lar\u0131n\u0131 veya yard\u0131mc\u0131 fonksiyonlar\u0131n\u0131 yazmak zorunda kal\u0131r, bu da kod tekrar\u0131na, bak\u0131m zorlu\u011funa ve potansiyel g\u00fcvenlik a\u00e7\u0131klar\u0131na yol a\u00e7ar. Bu kadar \u00e7ok manuel i\u015flem ve k\u0131s\u0131tlama, geli\u015ftirme s\u00fcrecini yava\u015flat\u0131r ve hata ay\u0131klamay\u0131 zorla\u015ft\u0131r\u0131r. \u0130\u015fte tam da bu noktada, Modern web uygulamalar\u0131, kullan\u0131c\u0131 aray\u00fcz\u00fcn\u00fcn karma\u015f\u0131kl\u0131\u011f\u0131 artt\u0131k\u00e7a, taray\u0131c\u0131 URL’sinin de uygulama state’inin \u00f6nemli bir par\u00e7as\u0131 haline gelmesini gerektiriyor. Ancak yukar\u0131da bahsetti\u011fimiz gibi, Next.js’in yerle\u015fik mekanizmalar\u0131 bu senkronizasyonu sa\u011flamada baz\u0131 temel eksikliklere sahip. \u0130\u015fte tam bu noktada Manuel URL y\u00f6netimine k\u0131yasla, Next.js projelerinize <\/code><\/p>\n Bu komut, \n Mevcut arama: {searchTerm}<\/strong>{' '}\n nuqs<\/code> gibi modern k\u00fct\u00fcphaneler bu zorluklar\u0131 a\u015fmak i\u00e7in g\u00fc\u00e7l\u00fc ve zarif bir \u00e7\u00f6z\u00fcm sunuyor. Bu makalede, nuqs<\/code>‘un Next.js projelerinizde URL arama parametrelerini nas\u0131l tip-g\u00fcvenli, reaktif ve zahmetsiz bir \u015fekilde y\u00f6netmenizi sa\u011flad\u0131\u011f\u0131n\u0131 derinlemesine inceleyece\u011fiz.<\/p>\nnuqs<\/code>‘un sundu\u011fu avantajlar\u0131 ke\u015ffedecek, b\u00f6ylece kullan\u0131c\u0131 deneyiminizi geli\u015ftirirken geli\u015ftirme s\u00fcrecinizi de b\u00fcy\u00fck \u00f6l\u00e7\u00fcde kolayla\u015ft\u0131racaks\u0131n\u0131z. Haz\u0131rsan\u0131z, URL parametre y\u00f6netimini bir sonraki seviyeye ta\u015f\u0131yal\u0131m!<\/p>\n?kategori=elektronik&sayfa=2&s\u0131rala=fiyat<\/code> gibi) olarak tutmak, hem SEO a\u00e7\u0131s\u0131ndan faydal\u0131d\u0131r hem de kullan\u0131c\u0131lar\u0131n belirli bir durumu do\u011frudan payla\u015fmas\u0131n\u0131 veya yer i\u015faretlemesini sa\u011flar. Ancak bu pratik yakla\u015f\u0131m\u0131n beraberinde getirdi\u011fi baz\u0131 zorluklar vard\u0131r ve bunlar geli\u015ftiriciler i\u00e7in ciddi ba\u015f a\u011fr\u0131lar\u0131na yol a\u00e7abilir.<\/p>\nsayfa=2<\/code>) asl\u0131nda bir say\u0131 olmas\u0131na ra\u011fmen, JavaScript taraf\u0131na \"2\"<\/code> olarak ula\u015f\u0131r. Bir filtrenin aktif olup olmad\u0131\u011f\u0131n\u0131 belirten boolean bir de\u011fer (aktif=true<\/code>) ise yine \"true\"<\/code> string’i olarak gelir. Bu durum, her parametreyi manuel olarak do\u011fru veri tipine d\u00f6n\u00fc\u015ft\u00fcrme ihtiyac\u0131n\u0131 do\u011furur. \u00d6rne\u011fin, bir sayfa numaras\u0131n\u0131 kullanmadan \u00f6nce parseInt()<\/code> ile say\u0131ya \u00e7evirmeniz veya bir boolean de\u011feri \"true\" === value<\/code> \u015feklinde kontrol etmeniz gerekir. Bu manuel d\u00f6n\u00fc\u015ft\u00fcrmeler, uygulaman\u0131n farkl\u0131 yerlerinde tekrarlanma e\u011filimindedir ve kolayca hata yap\u0131lmas\u0131na neden olabilir. Yanl\u0131\u015f bir d\u00f6n\u00fc\u015f\u00fcm veya eksik bir kontrol, uygulaman\u0131zda beklenmedik davran\u0131\u015flara veya hatalara yol a\u00e7abilir.<\/p>\nuseSearchParams<\/code> hook’u, URL’deki arama parametrelerine eri\u015fim sa\u011flar, ancak \u00f6nemli bir k\u0131s\u0131tlamas\u0131 vard\u0131r: yaln\u0131zca okuma (read-only) yetene\u011fine sahiptir. Yani, bu hook arac\u0131l\u0131\u011f\u0131yla URL’deki parametreleri okuyabilir, ancak do\u011frudan de\u011fi\u015ftiremezsiniz. Parametreleri de\u011fi\u015ftirmek istedi\u011finizde, genellikle next\/navigation<\/code> mod\u00fcl\u00fcnden useRouter<\/code> hook’unu kullanarak programatik olarak navigasyon (router.push()<\/code> veya router.replace()<\/code>) yapman\u0131z gerekir. Bu da demektir ki, basit bir arama kutusuna yaz\u0131lan her karakterde URL’yi g\u00fcncellemek veya bir filtre se\u00e7ildi\u011finde URL’ye yeni bir parametre eklemek i\u00e7in karma\u015f\u0131k bir state y\u00f6netimi ve router etkile\u015fimi kurman\u0131z gerekir. Bu yakla\u015f\u0131m, gereksiz yeniden render’lara veya istenmeyen tam sayfa yenilemelerine yol a\u00e7abilir, bu da kullan\u0131c\u0131 deneyimini olumsuz etkiler.<\/p>\nnuqs<\/code> gibi k\u00fct\u00fcphaneler devreye girerek bu geleneksel zorluklar\u0131 modern ve tip-g\u00fcvenli bir yakla\u015f\u0131mla \u00e7\u00f6zmeyi hedefler.<\/p>\nnuqs Nedir ve Next.js’te URL Parametre Y\u00f6netimine Nas\u0131l Devrim Getirir?<\/h2>\n
nuqs<\/code>, Next.js uygulamalar\u0131n\u0131zdaki URL arama parametreleri y\u00f6netimini ba\u015ftan a\u015fa\u011f\u0131 yeniden tan\u0131mlayan g\u00fc\u00e7l\u00fc ve hafif bir k\u00fct\u00fcphane olarak \u00f6ne \u00e7\u0131k\u0131yor. Temel felsefesi, geli\u015ftiricilere tip-g\u00fcvenli\u011fi, reaktiflik ve kullan\u0131m kolayl\u0131\u011f\u0131n\u0131 bir arada sunarak, URL’leri uygulama state’inizin birinci s\u0131n\u0131f bir vatanda\u015f\u0131 haline getirmektir.<\/p>\nnuqs<\/code>, \u00f6zellikle React’\u0131n useState<\/code> hook’undan ilham alan bir API sunar. T\u0131pk\u0131 bir bile\u015fenin i\u00e7 state’ini y\u00f6netti\u011finiz gibi, useQueryState<\/code> ve useQueryStates<\/code> gibi hook’lar arac\u0131l\u0131\u011f\u0131yla URL arama parametrelerini de y\u00f6netebilirsiniz. Bu, geli\u015ftiricilerin URL parametrelerini d\u00fc\u015f\u00fcnme ve bunlarla etkile\u015fim kurma bi\u00e7iminde devrim yarat\u0131r. Art\u0131k manuel ayr\u0131\u015ft\u0131rma, serile\u015ftirme ve router etkile\u015fimiyle u\u011fra\u015fmak yerine, t\u0131pk\u0131 lokal bir state’i g\u00fcncelliyormu\u015f gibi URL parametrelerini do\u011frudan g\u00fcncelleyebilir ve bu g\u00fcncellemelerin reaktif bir \u015fekilde bile\u015fenlerinize yans\u0131d\u0131\u011f\u0131n\u0131 g\u00f6rebilirsiniz. Bu sayede, Next.js’in sa\u011flad\u0131\u011f\u0131 h\u0131zl\u0131 sayfa ge\u00e7i\u015fleri (client-side routing) ve g\u00fc\u00e7l\u00fc sunucu taraf\u0131 render (SSR) yetenekleriyle kusursuz bir uyum i\u00e7inde \u00e7al\u0131\u015f\u0131r.<\/p>\nnuqs<\/code>‘un Temel \u00d6zellikleri ve Avantajlar\u0131 Nelerdir?<\/h3>\n\n
nuqs<\/code>‘un en dikkat \u00e7ekici \u00f6zelli\u011fi, TypeScript ile m\u00fckemmel entegrasyonudur. Tan\u0131mlad\u0131\u011f\u0131n\u0131z URL parametrelerinin tiplerini otomatik olarak \u00e7\u0131kar\u0131r ve bu sayede yanl\u0131\u015f tipte de\u011fer atamalar\u0131n\u0131 veya okumalar\u0131n\u0131 derleme zaman\u0131nda yakalaman\u0131z\u0131 sa\u011flar. Bu, \u00f6zellikle b\u00fcy\u00fck ve karma\u015f\u0131k projelerde hata olas\u0131l\u0131\u011f\u0131n\u0131 \u00f6nemli \u00f6l\u00e7\u00fcde azalt\u0131r ve geli\u015ftirici deneyimini art\u0131r\u0131r.<\/li>\nnumber<\/code>), boolean’lar (boolean<\/code>) ve diziler (array<\/code>) gibi temel veri tipleri i\u00e7in dahili ayr\u0131\u015ft\u0131r\u0131c\u0131lar (parsers) ve serile\u015ftiriciler (serializers) sunar. Bu, elle parseInt()<\/code> veya JSON.stringify()<\/code> gibi i\u015flemleri yapma ihtiyac\u0131n\u0131 ortadan kald\u0131r\u0131r. Sadece parametrenizin tipini belirtmeniz yeterlidir, gerisini nuqs<\/code> halleder.<\/li>\nDate<\/code> objeleri, karma\u015f\u0131k JSON yap\u0131lar\u0131 veya belirli bir formatta string’ler gibi \u00f6zel veri tiplerini bile URL’de g\u00fcvenli bir \u015fekilde y\u00f6netebilirsiniz.<\/li>\nuseQueryState<\/code> hook’u, t\u0131pk\u0131 useState<\/code> gibi \u00e7al\u0131\u015f\u0131r. URL’deki bir parametre de\u011fi\u015fti\u011finde, ilgili bile\u015fenler otomatik olarak yeniden render edilir ve en g\u00fcncel de\u011fere eri\u015fir. Bu reaktif yap\u0131, kullan\u0131c\u0131 aray\u00fcz\u00fcn\u00fcz\u00fcn her zaman URL ile senkronize kalmas\u0131n\u0131 sa\u011flar.<\/li>\nnuqs<\/code>, bu durumu \u00f6nlemek i\u00e7in dahili debounce<\/code> se\u00e7ene\u011fi sunar, b\u00f6ylece URL g\u00fcncellemelerini belirli bir gecikmeyle yapabilirsiniz.<\/li>\n'use client'<\/code> direktifiyle, server komponentlerinde ise ba\u015flang\u0131\u00e7 de\u011ferlerini ayarlayarak rahatl\u0131kla kullan\u0131labilir.<\/li>\nnuqs<\/code>, server component’lerde ba\u015flang\u0131\u00e7 de\u011ferlerini okuma yetene\u011fi sunarak, hem ilk y\u00fcklemede do\u011fru URL state’inin olmas\u0131n\u0131 sa\u011flar hem de SEO dostu URL’ler olu\u015fturman\u0131za yard\u0131mc\u0131 olur.<\/li>\n<\/ul>\nnuqs<\/code> geli\u015ftirici verimlili\u011fini inan\u0131lmaz derecede art\u0131r\u0131r. Daha az kod, daha az hata ve daha iyi bir geli\u015ftirme deneyimi demektir. URL parametrelerini art\u0131k sadece bir string y\u0131\u011f\u0131n\u0131 olarak de\u011fil, tip-g\u00fcvenli ve reaktif bir uygulama state’i par\u00e7as\u0131 olarak d\u00fc\u015f\u00fcnebilirsiniz. Bu, \u00f6zellikle karma\u015f\u0131k filtreleme, s\u0131ralama veya paginasyon i\u00e7eren Next.js uygulamalar\u0131 geli\u015ftirenler i\u00e7in ger\u00e7ek bir devrim niteli\u011findedir.<\/p>\nnuqs Kurulumu ve \u0130lk Ad\u0131mlar: Basit Bir Arama Parametresi Nas\u0131l Eklenir?<\/h2>\n
nuqs<\/code>‘u entegre etmek olduk\u00e7a basittir ve birka\u00e7 ad\u0131mdan olu\u015fur. Bu b\u00f6l\u00fcmde, k\u00fct\u00fcphaneyi projenize nas\u0131l ekleyece\u011finizi ve basit bir arama parametresini URL’ye nas\u0131l dahil edece\u011finizi ad\u0131m ad\u0131m g\u00f6rece\u011fiz. Bu ilk ad\u0131mlar, nuqs<\/code>‘un temel mant\u0131\u011f\u0131n\u0131 anlaman\u0131za ve hemen kullanmaya ba\u015flaman\u0131za yard\u0131mc\u0131 olacakt\u0131r.<\/p>\nKurulum: Projenize nuqs’u Entegre Etmek<\/h3>\n
nuqs<\/code>‘u projenize eklemek i\u00e7in favori paket y\u00f6neticinizi kullanabilirsiniz. Terminalinizi a\u00e7\u0131n ve a\u015fa\u011f\u0131daki komutlardan birini \u00e7al\u0131\u015ft\u0131r\u0131n:<\/p>\nnpm install nuqs\n# veya\nyarn add nuqs\n# veya\npnpm add nuqs\n<\/pre>\nnuqs<\/code> k\u00fct\u00fcphanesini projenizin ba\u011f\u0131ml\u0131l\u0131klar\u0131na ekleyecektir. Kurulum tamamland\u0131ktan sonra, k\u00fct\u00fcphanenin sundu\u011fu hook'lar\u0131 Next.js bile\u015fenlerinizde kullanmaya haz\u0131rs\u0131n\u0131z demektir. Ek olarak bir next.config.js<\/code> ayar\u0131 yapman\u0131za gerek yoktur, nuqs<\/code> kutudan \u00e7\u0131kt\u0131\u011f\u0131 gibi \u00e7o\u011fu Next.js projesiyle uyumludur.<\/p>\nTemel Kullan\u0131m:
useQueryState<\/code> Hook'u ile Tan\u0131\u015fma<\/h3>\nnuqs<\/code>'un kalbinde, React'\u0131n useState<\/code> hook'una benzer bir aray\u00fcze sahip olan useQueryState<\/code> hook'u yer al\u0131r. Bu hook, tek bir URL arama parametresini y\u00f6netmek i\u00e7in kullan\u0131l\u0131r. Gelin, bir arama kutusuna yaz\u0131lan terimi URL'ye nas\u0131l yans\u0131tabilece\u011finizi g\u00f6steren basit bir \u00f6rnekle ba\u015flayal\u0131m.<\/p>\n'use client';\n\nimport { useQueryState } from 'nuqs';\nimport { useEffect } from 'react';\n\nfunction SearchComponent() {\n \/\/ 'q' ad\u0131nda bir URL arama parametresi tan\u0131ml\u0131yoruz.\n \/\/ \u0130lk de\u011fer olarak bo\u015f bir string ('') kullanmas\u0131n\u0131 belirtiyoruz.\n \/\/ shallow: false (varsay\u0131lan), tam sayfa yenileme yapar, true client-side navigasyon yapar.\n const [searchTerm, setSearchTerm] = useQueryState('q', {\n defaultValue: '',\n shallow: false,\n });\n\n \/\/ searchTerm de\u011feri de\u011fi\u015fti\u011finde bir yan etki (side effect) olu\u015ftural\u0131m.\n \/\/ Bu, URL'nin ve bile\u015fen state'inin senkronize oldu\u011funu g\u00f6sterir.\n useEffect(() => {\n console.log('Arama terimi URL\\'de de\u011fi\u015fti:', searchTerm);\n \/\/ Bu noktada arama sonu\u00e7lar\u0131n\u0131 tetikleyebilirsiniz.\n }, [searchTerm]);\n\n return (\n \u00dcr\u00fcn Arama<\/h3>\n