Next.js uygulamalarında URL arama parametreleri (search params) yönetimi, karmaşıklaşmaya eğilimli ve çoğu zaman geliştiriciler için bir baş ağrısı kaynağı olabilen bir konudur. Genellikle string olarak gelen bu parametreleri elle ayrıştırmak, doğru tiplere dönüştürmek ve uygulama state’i ile senkronize etmek, hem zaman alıcı hem de hata yapmaya açık bir süreçtir. Neyse ki, nuqs gibi modern kütüphaneler bu zorlukları aşmak için güçlü ve zarif bir çözüm sunuyor. Bu makalede, nuqs‘un Next.js projelerinizde URL arama parametrelerini nasıl tip-güvenli, reaktif ve zahmetsiz bir şekilde yönetmenizi sağladığını derinlemesine inceleyeceğiz.

Eğer siz de Next.js projelerinizde URL’deki sorgu parametrelerinin dağınıklığıyla mücadele ediyorsanız, bu makale size aradığınız netliği ve pratik çözümleri sunacak. Kod örnekleri, gerçek dünya senaryoları ve ileri düzey ipuçları ile nuqs‘un sunduğu avantajları keşfedecek, böylece kullanıcı deneyiminizi geliştirirken geliştirme sürecinizi de büyük ölçüde kolaylaştıracaksınız. Hazırsanız, URL parametre yönetimini bir sonraki seviyeye taşıyalım!

Web uygulamalarının dinamik doğası gereği, kullanıcı etkileşimlerini veya sayfa durumunu URL’ler aracılığıyla iletmek yaygın bir yöntemdir. Özellikle Next.js gibi çerçevelerde, bir kullanıcının filtrelediği bir ürün listesini, görüntülediği sayfa numarasını veya uyguladığı bir sıralama seçeneğini URL’de arama parametreleri (?kategori=elektronik&sayfa=2&sırala=fiyat gibi) olarak tutmak, hem SEO açısından faydalıdır hem de kullanıcıların belirli bir durumu doğrudan paylaşmasını veya yer işaretlemesini sağlar. Ancak bu pratik yaklaşımın beraberinde getirdiği bazı zorluklar vardır ve bunlar geliştiriciler için ciddi baş ağrılarına yol açabilir.

Bu parametrelerin ilk ve en büyük sorunu, tarayıcı tarafından her zaman bir string olarak işlenmesidir. Sayfa numarası (sayfa=2) aslında bir sayı olmasına rağmen, JavaScript tarafına "2" olarak ulaşır. Bir filtrenin aktif olup olmadığını belirten boolean bir değer (aktif=true) ise yine "true" string’i olarak gelir. Bu durum, her parametreyi manuel olarak doğru veri tipine dönüştürme ihtiyacını doğurur. Örneğin, bir sayfa numarasını kullanmadan önce parseInt() ile sayıya çevirmeniz veya bir boolean değeri "true" === value şeklinde kontrol etmeniz gerekir. Bu manuel dönüştürmeler, uygulamanın farklı yerlerinde tekrarlanma eğilimindedir ve kolayca hata yapılmasına neden olabilir. Yanlış bir dönüşüm veya eksik bir kontrol, uygulamanızda beklenmedik davranışlara veya hatalara yol açabilir.

Next.js’in App Router yapısında veya Pages Router’da kullanılan useSearchParams hook’u, URL’deki arama parametrelerine erişim sağlar, ancak önemli bir kısıtlaması vardır: yalnızca okuma (read-only) yeteneğine sahiptir. Yani, bu hook aracılığıyla URL’deki parametreleri okuyabilir, ancak doğrudan değiştiremezsiniz. Parametreleri değiştirmek istediğinizde, genellikle next/navigation modülünden useRouter hook’unu kullanarak programatik olarak navigasyon (router.push() veya router.replace()) yapmanız gerekir. Bu da demektir ki, basit bir arama kutusuna yazılan her karakterde URL’yi güncellemek veya bir filtre seçildiğinde URL’ye yeni bir parametre eklemek için karmaşık bir state yönetimi ve router etkileşimi kurmanız gerekir. Bu yaklaşım, gereksiz yeniden render’lara veya istenmeyen tam sayfa yenilemelerine yol açabilir, bu da kullanıcı deneyimini olumsuz etkiler.

Dahası, karmaşık veri yapılarını (örneğin bir dizi kategori seçimi veya bir fiyat aralığı objesi) URL’de temsil etmek ve bunları güvenli bir şekilde ayrıştırıp serialize etmek başlı başına bir meydan okumadır. Geliştiriciler genellikle bu tür durumlar için kendi özel hook’larını veya yardımcı fonksiyonlarını yazmak zorunda kalır, bu da kod tekrarına, bakım zorluğuna ve potansiyel güvenlik açıklarına yol açar. Bu kadar çok manuel işlem ve kısıtlama, geliştirme sürecini yavaşlatır ve hata ayıklamayı zorlaştırır. İşte tam da bu noktada, nuqs gibi kütüphaneler devreye girerek bu geleneksel zorlukları modern ve tip-güvenli bir yaklaşımla çözmeyi hedefler.

nuqs Nedir ve Next.js’te URL Parametre Yönetimine Nasıl Devrim Getirir?

Modern web uygulamaları, kullanıcı arayüzünün karmaşıklığı arttıkça, tarayıcı URL’sinin de uygulama state’inin önemli bir parçası haline gelmesini gerektiriyor. Ancak yukarıda bahsettiğimiz gibi, Next.js’in yerleşik mekanizmaları bu senkronizasyonu sağlamada bazı temel eksikliklere sahip. İşte tam bu noktada nuqs, Next.js uygulamalarınızdaki URL arama parametreleri yönetimini baştan aşağı yeniden tanımlayan güçlü ve hafif bir kütüphane olarak öne çıkıyor. Temel felsefesi, geliştiricilere tip-güvenliği, reaktiflik ve kullanım kolaylığını bir arada sunarak, URL’leri uygulama state’inizin birinci sınıf bir vatandaşı haline getirmektir.

nuqs, özellikle React’ın useState hook’undan ilham alan bir API sunar. Tıpkı bir bileşenin iç state’ini yönettiğiniz gibi, useQueryState ve useQueryStates gibi hook’lar aracılığıyla URL arama parametrelerini de yönetebilirsiniz. Bu, geliştiricilerin URL parametrelerini düşünme ve bunlarla etkileşim kurma biçiminde devrim yaratır. Artık manuel ayrıştırma, serileştirme ve router etkileşimiyle uğraşmak yerine, tıpkı lokal bir state’i güncelliyormuş gibi URL parametrelerini doğrudan güncelleyebilir ve bu güncellemelerin reaktif bir şekilde bileşenlerinize yansıdığını görebilirsiniz. Bu sayede, Next.js’in sağladığı hızlı sayfa geçişleri (client-side routing) ve güçlü sunucu tarafı render (SSR) yetenekleriyle kusursuz bir uyum içinde çalışır.

nuqs‘un Temel Özellikleri ve Avantajları Nelerdir?

• Tip Çıkarımı (Type Inference) ve Tip-Güvenliği: nuqs‘un en dikkat çekici özelliği, TypeScript ile mükemmel entegrasyonudur. Tanımladığınız URL parametrelerinin tiplerini otomatik olarak çıkarır ve bu sayede yanlış tipte değer atamalarını veya okumalarını derleme zamanında yakalamanızı sağlar. Bu, özellikle büyük ve karmaşık projelerde hata olasılığını önemli ölçüde azaltır ve geliştirici deneyimini artırır.
• Otomatik Ayrıştırma ve Serileştirme: Sayılar (number), boolean’lar (boolean) ve diziler (array) gibi temel veri tipleri için dahili ayrıştırıcılar (parsers) ve serileştiriciler (serializers) sunar. Bu, elle parseInt() veya JSON.stringify() gibi işlemleri yapma ihtiyacını ortadan kaldırır. Sadece parametrenizin tipini belirtmeniz yeterlidir, gerisini nuqs halleder.
• Özel Ayrıştırıcılar (Custom Parsers): Dahili tiplerin ötesine geçmeniz gerektiğinde, kendi özel ayrıştırıcılarınızı tanımlamanıza olanak tanır. Bu sayede Date objeleri, karmaşık JSON yapıları veya belirli bir formatta string’ler gibi özel veri tiplerini bile URL’de güvenli bir şekilde yönetebilirsiniz.
• Reaktif ve Güncel State: useQueryState hook’u, tıpkı useState gibi çalışır. URL’deki bir parametre değiştiğinde, ilgili bileşenler otomatik olarak yeniden render edilir ve en güncel değere erişir. Bu reaktif yapı, kullanıcı arayüzünüzün her zaman URL ile senkronize kalmasını sağlar.
• Debouncing Desteği: Arama kutuları gibi sık güncelleme gerektiren alanlarda, her karakter girişinde URL’yi güncellemek performansı düşürebilir. nuqs, bu durumu önlemek için dahili debounce seçeneği sunar, böylece URL güncellemelerini belirli bir gecikmeyle yapabilirsiniz.
• Next.js App Router ve Pages Router Uyumluluğu: Hem Next.js’in eski Pages Router yapısında hem de yeni App Router yapısında sorunsuz bir şekilde çalışır. Client komponentlerinde 'use client' direktifiyle, server komponentlerinde ise başlangıç değerlerini ayarlayarak rahatlıkla kullanılabilir.
• Sunucu Tarafı Güvenliği (Server-Side Safety): nuqs, server component’lerde başlangıç değerlerini okuma yeteneği sunarak, hem ilk yüklemede doğru URL state’inin olmasını sağlar hem de SEO dostu URL’ler oluşturmanıza yardımcı olur.

Manuel URL yönetimine kıyasla, nuqs geliştirici verimliliğini inanılmaz derecede artırır. Daha az kod, daha az hata ve daha iyi bir geliştirme deneyimi demektir. URL parametrelerini artık sadece bir string yığını olarak değil, tip-güvenli ve reaktif bir uygulama state’i parçası olarak düşünebilirsiniz. Bu, özellikle karmaşık filtreleme, sıralama veya paginasyon içeren Next.js uygulamaları geliştirenler için gerçek bir devrim niteliğindedir.

nuqs Kurulumu ve İlk Adımlar: Basit Bir Arama Parametresi Nasıl Eklenir?

Next.js projelerinize nuqs‘u entegre etmek oldukça basittir ve birkaç adımdan oluşur. Bu bölümde, kütüphaneyi projenize nasıl ekleyeceğinizi ve basit bir arama parametresini URL’ye nasıl dahil edeceğinizi adım adım göreceğiz. Bu ilk adımlar, nuqs‘un temel mantığını anlamanıza ve hemen kullanmaya başlamanıza yardımcı olacaktır.

Kurulum: Projenize nuqs’u Entegre Etmek

nuqs‘u projenize eklemek için favori paket yöneticinizi kullanabilirsiniz. Terminalinizi açın ve aşağıdaki komutlardan birini çalıştırın:

npm install nuqs
# veya
yarn add nuqs
# veya
pnpm add nuqs

Bu komut, nuqs kütüphanesini projenizin bağımlılıklarına ekleyecektir. Kurulum tamamlandıktan sonra, kütüphanenin sunduğu hook'ları Next.js bileşenlerinizde kullanmaya hazırsınız demektir. Ek olarak bir next.config.js ayarı yapmanıza gerek yoktur, nuqs kutudan çıktığı gibi çoğu Next.js projesiyle uyumludur.

Temel Kullanım: useQueryState Hook'u ile Tanışma

nuqs'un kalbinde, React'ın useState hook'una benzer bir arayüze sahip olan useQueryState hook'u yer alır. Bu hook, tek bir URL arama parametresini yönetmek için kullanılır. Gelin, bir arama kutusuna yazılan terimi URL'ye nasıl yansıtabileceğinizi gösteren basit bir örnekle başlayalım.

'use client';

import { useQueryState } from 'nuqs';
import { useEffect } from 'react';

function SearchComponent() {
  // 'q' adında bir URL arama parametresi tanımlıyoruz.
  // İlk değer olarak boş bir string ('') kullanmasını belirtiyoruz.
  // shallow: false (varsayılan), tam sayfa yenileme yapar, true client-side navigasyon yapar.
  const [searchTerm, setSearchTerm] = useQueryState('q', {
    defaultValue: '',
    shallow: false,
  });

  // searchTerm değeri değiştiğinde bir yan etki (side effect) oluşturalım.
  // Bu, URL'nin ve bileşen state'inin senkronize olduğunu gösterir.
  useEffect(() => {
    console.log('Arama terimi URL\'de değişti:', searchTerm);
    // Bu noktada arama sonuçlarını tetikleyebilirsiniz.
  }, [searchTerm]);

  return (
    

      
Ürün Arama
       setSearchTerm(e.target.value)}
        placeholder="Arama terimi girin..."
        style={{ padding: '8px', borderRadius: '4px', border: '1px solid #ccc', width: '300px' }}
      />
      {searchTerm && (
        

          Mevcut arama: {searchTerm}{' '}
           setSearchTerm(null)} style={{ marginLeft: '10px' }}>
            Temizle
          
        
      )}
      

        URL: /sayfa{searchTerm ? ?q=${searchTerm} : ''}
      
    
  );
}

export default SearchComponent;

Yukarıdaki kod bloğunda, SearchComponent adında basit bir React bileşeni oluşturduk. Bu bileşen, bir arama girişi (input) içerir ve kullanıcının girdiği metni URL'deki q parametresiyle senkronize eder. İşte adımların açıklaması:

1. 'use client';: Next.js App Router'da useQueryState gibi hook'lar client tarafında çalışır, bu yüzden bu direktifi eklemeyi unutmayın.
2. import { useQueryState } from 'nuqs';: Gerekli hook'u nuqs kütüphanesinden içe aktarıyoruz.
3. const [searchTerm, setSearchTerm] = useQueryState('q', { defaultValue: '', shallow: false });:
   • 'q': URL'de yönetmek istediğimiz parametrenin adıdır. Yani URL'de ?q=değer şeklinde görünecektir.
   • { defaultValue: '' }: Bu parametre URL'de yoksa, searchTerm'in başlangıç değeri boş bir string olacaktır. Bu, hem tip-güvenliği sağlar hem de server-side render durumlarında bir başlangıç değeri olmasını garantiler.
   • shallow: false: Bu, bir parametre değiştiğinde tam sayfa yenilemesi yapılacağını belirtir. Eğer sadece client-side routing ile URL'yi güncellemek ve sayfa yenilemesi yapmamak isterseniz shallow: true olarak ayarlayabilirsiniz. Genellikle filtreleme gibi durumlarda shallow: true tercih edilir, ancak arama motorları için tam sayfa yenilemesi de tercih edilebilir.
4. value={searchTerm || ''}: Input alanının değerini searchTerm ile bağlıyoruz. searchTerm başlangıçta null olabilir (URL'de parametre yoksa ve defaultValue ayarlanmadıysa), bu yüzden boş string'e dönüştürmek iyi bir pratiktir.
5. onChange={(e) => setSearchTerm(e.target.value)}: Kullanıcı input alanına yazı yazdığında, setSearchTerm fonksiyonunu çağırarak URL'deki q parametresini güncelliyoruz. nuqs, bu çağrıyı algılar ve URL'yi otomatik olarak günceller.
6. useEffect: searchTerm değeri her değiştiğinde (yani URL'deki q parametresi güncellendiğinde), useEffect içindeki kod çalışacaktır. Bu, URL'ye dayalı veri çekme veya başka yan etkileri tetiklemek için kullanabileceğiniz reaktif bir mekanizmadır.
7. setSearchTerm(null): Bir URL parametresini tamamen kaldırmak istediğinizde, setter fonksiyonunu null (veya undefined) ile çağırabilirsiniz. Bu, URL'den ?q=değer kısmını kaldıracaktır.

Bu basit örnekle, nuqs'un URL arama parametrelerini yönetmeyi nasıl kolaylaştırdığını ve tip-güvenliğini nasıl sağladığını görmüş olmalısınız. Artık manuel olarak router.push() çağrıları yapma veya string'leri dönüştürme karmaşasından kurtulmuş durumdayız.

Tip-Güvenli URL Parametreleri: nuqs ile Veri Tiplerini Korumak Nasıl Mümkün?

URL arama parametrelerinin en büyük zorluklarından biri, tarayıcı tarafından her zaman bir string olarak ele alınmasıdır. Bu durum, bir sayfa numarası (number), bir filtre anahtarı (boolean) veya seçili kategorilerin bir listesi (string[]) gibi farklı veri tiplerini elle string'e dönüştürme ve tekrar eski haline getirme gereksinimi doğurur. nuqs, bu süreci otomatikleştirerek ve tip-güvenliğini sağlayarak geliştiricilerin hayatını kolaylaştırır. Böylece, uygulamanızın daha az hataya açık ve daha sağlam olmasını garantiler.

Sayılar, Boolean'lar ve Diziler İçin Otomatik Tür Dönüşümü

nuqs, en yaygın kullanılan veri tipleri için dahili ayrıştırıcılar (parsers) ile gelir. Bu sayede, parseAs seçeneğini kullanarak parametrenizin beklenen veri tipini belirtebilirsiniz. nuqs, URL'den okunan string değeri otomatik olarak belirtilen tipe dönüştürür ve aynı şekilde JavaScript'ten gelen değeri de URL'ye uygun string formatına çevirir.

Sayı Örneği: Sayfa Numarası Yönetimi

Bir paginasyon bileşeninde sayfa numarasını URL'de tutmak oldukça yaygındır. nuqs ile bu, çok basittir:

'use client';

import { useQueryState } from 'nuqs';

function Paginasyon() {
  const [page, setPage] = useQueryState('page', {
    defaultValue: 1, // URL'de 'page' yoksa başlangıç 1 olsun
    parseAs: 'number', // 'page' parametresini sayı olarak ayrıştır
  });

  return (
    

      
Paginasyon
      
Mevcut Sayfa: {page}
       setPage((p) => Math.max(1, (p || 1) - 1))} disabled={(page || 1) <= 1}>
        Önceki
      
       setPage((p) => (p || 1) + 1)} style={{ marginLeft: '10px' }}>
        Sonraki
      
      

        URL: /sayfam{page ? ?page=${page} : ''}
      
    
  );
}

export default Paginasyon;

Burada, parseAs: 'number' sayesinde, URL'den gelen "2" string'i otomatik olarak 2 sayısına dönüşür. setPage ile bir sayı gönderdiğinizde de, nuqs bunu otomatik olarak "2" string'ine çevirip URL'ye ekler. Tip güvenliği, TypeScript sayesinde page değişkeninin her zaman bir number olarak algılanmasıyla sağlanır.

Boolean Örneği: Aktif Filtre Durumu

Bir filtre kutusunun açık veya kapalı olma durumu gibi boolean değerler de nuqs ile kolayca yönetilebilir:

'use client';

import { useQueryState } from 'nuqs';

function FilterToggle() {
  const [showFilters, setShowFilters] = useQueryState('showFilters', {
    defaultValue: false,
    parseAs: 'boolean',
  });

  return (
    

      
Filtreleri Göster
      
         setShowFilters(e.target.checked)}
        />
        Filtreleri Göster
      
      
Filtreler şu an: {showFilters ? 'Açık' : 'Kapalı'}
      

        URL: /sayfam{showFilters ? ?showFilters=${showFilters} : ''}
      
    
  );
}

export default FilterToggle;

parseAs: 'boolean' ile "true" veya "false" string'leri otomatik olarak JavaScript'in true veya false boolean değerlerine dönüşür. Bu, manuel "true" === value kontrollerinden kurtulmanızı sağlar.

Dizi Örneği: Çoklu Kategori Seçimi

Birden fazla kategori seçimi gibi durumlarda, değerleri bir dizi olarak URL'de tutmak isteyebilirsiniz:

'use client';

import { useQueryState } from 'nuqs';

function CategoryFilter() {
  // 'categories' parametresini string dizisi olarak ayrıştır
  const [selectedCategories, setSelectedCategories] = useQueryState('categories', {
    defaultValue: [], // Başlangıçta boş dizi
    parseAs: 'array', // veya 'array(string)'
  });

  const allCategories = ['Elektronik', 'Giyim', 'Ev', 'Kitap'];

  const handleCategoryChange = (category) => {
    setSelectedCategories((prev) => {
      if (prev.includes(category)) {
        return prev.filter((cat) => cat !== category);
      }
      return [...prev, category];
    });
  };

  return (
    

      
Kategori Filtresi
      {allCategories.map((category) => (
        
           handleCategoryChange(category)}
          />
          {category}
        
      ))}
      
Seçilen Kategoriler: {selectedCategories.length > 0 ? selectedCategories.join(', ') : 'Hiçbiri'}
      

        URL: /sayfam{selectedCategories.length > 0 ? ?categories=${selectedCategories.join(',')} : ''}
      
    
  );
}

export default CategoryFilter;

parseAs: 'array' veya parseAs: 'array(string)' kullanarak, URL'deki virgülle ayrılmış bir string'i (örneğin ?categories=Elektronik,Giyim) otomatik olarak bir string dizisine dönüştürebilirsiniz. setSelectedCategories'e bir dizi geçtiğinizde de, nuqs bunu URL için uygun string formatına dönüştürecektir.

Özel Tip Dönüştürücüler ile Esneklik Kazanmak

Bazen number, boolean veya array gibi temel tiplerin ötesine geçmeniz gerekebilir. Örneğin, bir tarih objesini, karmaşık bir JSON nesnesini veya belirli bir formatta string'i URL'de saklamak isteyebilirsiniz. nuqs, bu tür senaryolar için createParser fonksiyonu aracılığıyla kendi özel tip dönüştürücülerinizi (parsers) tanımlamanıza olanak tanır. Bu, kütüphanenin sunduğu en güçlü esnekliklerden biridir.

Tarih Objesi Örneği: Rezervasyon Tarihi

Bir rezervasyon sisteminde, kullanıcının seçtiği tarihi URL'de tutmak isteyebilirsiniz. JavaScript'in Date objeleri doğrudan URL'de saklanamaz, ancak ISO 8601 gibi bir string formatına dönüştürülebilir:

'use client';

import { useQueryState, createParser } from 'nuqs';
import { useState } from 'react';

// Özel bir tarih parser'ı oluşturuyoruz
const dateParser = createParser({
  parse: (value) => (value ? new Date(value) : null), // URL'den okunan string'i Date objesine dönüştür
  serialize: (value) => (value instanceof Date ? value.toISOString() : null), // Date objesini ISO string'ine dönüştür
});

function DatePickerComponent() {
  const [selectedDate, setSelectedDate] = useQueryState('date', {
    defaultValue: null, // Başlangıçta tarih seçili olmasın
    parser: dateParser, // Kendi özel parser'ımızı kullanıyoruz
  });

  const [inputDateString, setInputDateString] = useState(
    selectedDate ? selectedDate.toISOString().substring(0, 10) : ''
  );

  const handleDateChange = (e) => {
    const dateStr = e.target.value;
    setInputDateString(dateStr);
    if (dateStr) {
      setSelectedDate(new Date(dateStr));
    } else {
      setSelectedDate(null);
    }
  };

  return (
    

      
Tarih Seçimi
      
      
Seçilen Tarih: {selectedDate ? selectedDate.toLocaleDateString() : 'Yok'}
      

        URL: /sayfam{selectedDate ? ?date=${selectedDate.toISOString().substring(0, 10)} : ''}
      
    
  );
}

export default DatePickerComponent;

Bu örnekte, createParser ile hem parse (URL'den okurken) hem de serialize (URL'ye yazarken) fonksiyonlarını tanımlayarak Date objelerinin yönetimini tamamen kontrol altına aldık. nuqs, bu parser'ı kullanarak URL ile Date objesi arasında sorunsuz bir dönüşüm sağlar. Bu sayede, uygulamanızdaki tarih seçimi bileşenleri URL ile tip-güvenli bir şekilde senkronize edilebilir. Bu özellik, nuqs'un sadece temel tiplerle sınırlı kalmadığını, aynı zamanda karmaşık ve özel veri tipleri için de güçlü bir çözüm sunduğunu gösterir. Bu esneklik, geliştiricilere URL yönetiminde sınırsız olanaklar tanır ve uygulamanın karmaşıklığı ne olursa olsun tutarlı bir yaklaşım benimsemeyi mümkün kılar.

Gelişmiş nuqs Kullanımı: Performans, Debouncing ve Çoklu Parametre Yönetimi

nuqs, sadece temel URL parametre yönetimi sunmakla kalmaz, aynı zamanda daha karmaşık senaryolar ve performans optimizasyonları için gelişmiş özellikler de sağlar. Bu bölümde, kullanıcı deneyimini ve uygulamanızın performansını artıracak debouncing mekanizmasını, birden fazla URL parametresini eş zamanlı olarak yönetme yeteneğini ve shallow routing ile SSR entegrasyonu gibi konuları ele alacağız.

Debouncing ile Performansı Artırmak

Arama kutuları veya gerçek zamanlı filtreler gibi alanlarda kullanıcı girdisi çok hızlı değişebilir. Kullanıcının her tuş vuruşunda URL'yi anında güncellemek, tarayıcı geçmişinde çok sayıda giriş oluşturabilir ve gereksiz yeniden render'lara neden olarak performansı düşürebilir. nuqs, bu sorunu çözmek için debounce seçeneği sunar. Bu seçenek, URL güncellemesini belirli bir süre geciktirerek, kullanıcının duraklamasını bekler ve sadece son değeri URL'ye yansıtır.

'use client';

import { useQueryState } from 'nuqs';
import { useState } from 'react';

function DebouncedSearchInput() {
  // 'q' parametresini 500ms gecikmeli olarak güncelle
  const [searchTerm, setSearchTerm] = useQueryState('q', {
    defaultValue: '',
    debounce: 500, // 500 milisaniye gecikme
  });

  const [localInput, setLocalInput] = useState(searchTerm || '');

  const handleInputChange = (e) => {
    setLocalInput(e.target.value);
    setSearchTerm(e.target.value); // Bu çağrı debounced olacak
  };

  return (
    

      
Debounced Arama Kutusu
      
      
URL'deki arama terimi (debounced): {searchTerm}
      
Lokal girdi: {localInput}
      

        URL: /debounced-sayfam{searchTerm ? ?q=${searchTerm} : ''}
      
    
  );
}

export default DebouncedSearchInput;

Yukarıdaki örnekte, kullanıcı input alanına yazmaya başladığında, setSearchTerm çağrısı anında URL'yi güncellemez. Bunun yerine, 500 milisaniye bekler. Eğer bu süre içinde başka bir karakter yazılırsa, önceki gecikmeli güncelleme iptal edilir ve yeni bir 500ms'lik gecikme başlar. Bu, kullanıcının yazmayı bitirmesini bekleyerek URL'yi ve dolayısıyla tetiklenecek verileri yalnızca gerektiğinde güncellemek için harika bir yoldur. localInput state'i ise kullanıcının anlık girdisini UI'da anında göstermek için kullanılırken, searchTerm URL ile debounced bir şekilde senkronize kalır.

Birden Fazla Parametreyi Eş Zamanlı Yönetmek

Bir ürün listeleme sayfasında hem kategori, hem fiyat aralığı, hem de sıralama gibi birden fazla parametreyi aynı anda yönetmeniz gerekebilir. useQueryState tek bir parametre için harika olsa da, birçok parametrenin eş zamanlı ve koordineli yönetimi için nuqs, useQueryStates hook'unu sunar. Bu hook, tek bir çağrı ile birden fazla URL parametresini güncellemeyi ve bunların tip güvenliğini sağlamayı mümkün kılar.

'use client';

import { useQueryStates } from 'nuqs';
import { useEffect } from 'react';

function AdvancedFilterComponent() {
  const [{ search, category, sort, priceMin, priceMax }, setQueryStates] = useQueryStates({
    search: { parseAs: 'string', defaultValue: '' },
    category: { parseAs: 'string', defaultValue: 'all' },
    sort: { parseAs: 'string', defaultValue: 'newest' },
    priceMin: { parseAs: 'number', defaultValue: 0 },
    priceMax: { parseAs: 'number', defaultValue: 1000 },
  });

  useEffect(() => {
    console.log('Filtreler değişti:', { search, category, sort, priceMin, priceMax });
    // Bu noktada filtrelenmiş verileri çekebilirsiniz.
  }, [search, category, sort, priceMin, priceMax]);

  return (
    

      
Gelişmiş Filtre Yönetimi
      

        
          Arama:
           setQueryStates({ search: e.target.value })}
            style={{ marginLeft: '5px' }}
          />
        
      
      

        
          Kategori:
           setQueryStates({ category: e.target.value })}
            style={{ marginLeft: '5px' }}
          >
            Tümü
            Elektronik
            Giyim
          
        
      
      

        
          Sırala:
           setQueryStates({ sort: e.target.value })}
            style={{ marginLeft: '5px' }}
          >
            En Yeni
            Fiyat (Artan)
            Fiyat (Azalan)
          
        
      
      

        
          Fiyat Aralığı:
           setQueryStates({ priceMin: Number(e.target.value) })}
            style={{ marginLeft: '5px', width: '80px' }}
          />
          -
           setQueryStates({ priceMax: Number(e.target.value) })}
            style={{ marginLeft: '5px', width: '80px' }}
          />
        
      
       setQueryStates({ search: null, category: null, sort: null, priceMin: null, priceMax: null })} style={{ marginTop: '10px' }}>
        Filtreleri Temizle
      
      

        Mevcut URL Filtreleri: 
{JSON.stringify({ search, category, sort, priceMin, priceMax }, null, 2)}

      

  );

}
export default AdvancedFilterComponent;


useQueryStates hook'u, bir nesne alır ve bu nesnenin her anahtarı, yönetmek istediğiniz bir URL parametresini temsil eder. Her parametre için parseAs ve defaultValue gibi seçenekleri belirtebilirsiniz. setQueryStates fonksiyonu ise, bir nesne alarak birden fazla parametreyi tek bir işlemde günceller. Bu, tarayıcı geçmişine yalnızca tek bir giriş eklenmesini sağlar ve UI güncellemelerini optimize eder.
Uzman İpucu: Çoklu parametre güncellemelerinde setQueryStates kullanmak, ayrı ayrı güncellemeler yapmaktan daha verimlidir, çünkü bu işlem tarayıcı geçmişine tek bir giriş yapar ve gereksiz render'ları azaltır. Ayrıca null veya undefined değerleri atayarak parametreleri URL'den kaldırabilirsiniz.
Shallow Routing ve Server-Side Rendered (SSR) Parametreler
Shallow Routing (shallow: true): Next.js'te shallow routing, sayfa yenilemesi olmadan URL'yi güncelleme yeteneğidir. nuqs, useQueryState veya useQueryStates hook'larına shallow: true seçeneğini ekleyerek bu davranışı kolayca etkinleştirmenizi sağlar. Bu, özellikle client-side etkileşimlerle (örneğin bir filtreyi açıp kapatmak) URL'yi güncellemek ve sayfa state'ini korumak istediğiniz durumlarda kullanışlıdır. Örneğin, bir modal açıldığında URL'ye ?modal=true eklemek ve sayfayı yenilememek için idealdir.
'use client';

import { useQueryState } from 'nuqs';

function ModalComponent() {
  const [isModalOpen, setIsModalOpen] = useQueryState('modal', {
    defaultValue: false,
    parseAs: 'boolean',
    shallow: true, // Sayfa yenilemesi yapma
  });

  return (
    

      
Modal Durumu
       setIsModalOpen((prev) => !prev)}>
        Modalı {isModalOpen ? 'Kapat' : 'Aç'}
      
      {isModalOpen && (
        

          Bu bir modal içeriğidir.
        
      )}
      

        URL: /modal-sayfam{isModalOpen ? ?modal=${isModalOpen} : ''} (Shallow routing ile güncellenir)
      
    
  );
}

export default ModalComponent;


Server-Side Rendered (SSR) Parametreler: nuqs, Next.js'in server komponentleriyle de uyumludur. Server komponentlerinde doğrudan useQueryState kullanamasanız da (çünkü React hook'ları sadece client komponentlerde çalışır), URL'deki parametrelere erişmek için Next.js'in searchParams prop'unu kullanabilir ve bunu nuqs'un defaultValue veya initialValues (useQueryStates için) olarak besleyebilirsiniz. Bu, sayfanın ilk yüklenmesinde ve sunucu tarafında oluşturulurken doğru URL state'ine sahip olmasını sağlar, bu da SEO ve ilk yükleme performansı için kritik öneme sahiptir.
// app/page.tsx (Server Component)
import SearchComponent from '../components/SearchComponent'; // Önceki SearchComponent'i import ediyoruz
import Paginasyon from '../components/Paginasyon';
import FilterToggle from '../components/FilterToggle';
import CategoryFilter from '../components/CategoryFilter';
import DatePickerComponent from '../components/DatePickerComponent';
import DebouncedSearchInput from '../components/DebouncedSearchInput';
import AdvancedFilterComponent from '../components/AdvancedFilterComponent';
import ModalComponent from '../components/ModalComponent';

interface HomePageProps {
  searchParams: { [key: string]: string | string[] | undefined };
}

export default function HomePage({ searchParams }: HomePageProps) {
  // searchParams'ı doğrudan nuqs hook'larına beslemesek de,
  // bu, initial state'i ayarlamak için kullanılabilir.
  // nuqs, client tarafında kendi başına searchParams'ı okuyacaktır.
  // Ancak server komponentleri render edilirken,
  // nuqs client component içinde çalışmaya başlayana kadar URL'deki parametreler kullanılabilir durumda olacaktır.

  const initialSearchTerm = searchParams.q as string || '';
  const initialPage = Number(searchParams.page) || 1;
  const initialShowFilters = searchParams.showFilters === 'true';

  return (
    

      
nuqs ile Next.js URL Parametre Yönetimi
      
Bu sayfadaki bileşenler, URL'deki arama parametreleriyle etkileşim kurar ve onları tip-güvenli bir şekilde yönetir.

      
Örnek Uygulamalar
      
      
      
      
      
      
      
      

      
Sunucu Tarafından Okunan İlk Parametreler
      

        
Arama Terimi (q): {initialSearchTerm || 'Yok'}
        
Sayfa Numarası (page): {initialPage}
        
Filtreler Açık Mı? (showFilters): {initialShowFilters.toString()}
      

      

        Not: Yukarıdaki "Sunucu Tarafından Okunan İlk Parametreler" kısmı, Next.js'in searchParams prop'u aracılığıyla sunucu tarafında doğrudan URL parametrelerine nasıl erişilebileceğini gösterir. Client komponentleri (örneğin SearchComponent) ise kendi içlerinde nuqs kullanarak bu parametreleri reaktif bir şekilde yönetir.
      
    
  );
}


Bu gelişmiş özellikler sayesinde nuqs, Next.js uygulamalarınızda URL yönetimini sadece kolaylaştırmakla kalmaz, aynı zamanda daha sağlam, performanslı ve kullanıcı dostu hale getirir. Uygulamanızın ölçeği ve karmaşıklığı ne olursa olsun, nuqs size güçlü ve esnek bir araç seti sunar.
Vaka Analizi: E-ticaret Sitesi İçin Gelişmiş Filtreleme Sistemi
Şimdiye kadar nuqs'un temel ve gelişmiş özelliklerini gördük. Şimdi bu bilgileri, gerçek dünyadan bir senaryo üzerinde, bir e-ticaret sitesi için gelişmiş bir ürün filtreleme sistemi geliştirirken nasıl uygulayacağımıza bakalım. Bu vaka analizi, nuqs'un karmaşık bir kullanıcı arayüzünde ne kadar etkili ve verimli olabileceğini net bir şekilde ortaya koyacaktır.
Senaryo: Dinamik Ürün Listeleme ve Filtreleme
Hayal edin ki bir e-ticaret platformu geliştiriyorsunuz. Ürün listeleme sayfasında kullanıcılar:

• Belirli kategorileri seçebilir (çoklu seçim).
• Bir fiyat aralığı belirleyebilirler.
• İstedikleri markaları filtreleyebilirler (çoklu seçim).
• Ürünleri fiyata göre (artan/azalan) veya yeniliğe göre sıralayabilirler.
• Bir arama terimi girebilirler.
• Listede sayfalar arasında gezinebilirler.

Tüm bu filtreleme ve sıralama seçeneklerinin, kullanıcının sayfayı yenilemeden etkileşim kurabilmesi ve URL'de doğru bir şekilde temsil edilmesi gerekmektedir. Böylece kullanıcılar filtrelenmiş bir ürün listesinin URL'sini paylaşabilir veya yer işaretleyebilir.

Mevcut Durum Sorunu: Geleneksel Yaklaşımın Yetersizlikleri

Geleneksel olarak, böyle bir sistemi Next.js'in standart useSearchParams hook'u veya manuel state yönetimi ile kurmaya çalıştığımızda, hızla karmaşıklaşan bir kod yığını ile karşılaşırız:

1. Tip-Güvenliği Eksikliği: Her parametre string olarak gelir. Kategori listesini virgülle ayrılmış string'den diziye çevirme, fiyat aralığını sayıya dönüştürme gibi işlemlerin her yerde elle yapılması gerekir. Bu, TypeScript'in sağladığı faydaları azaltır.
2. Boilerplate Kod: Her bir filtre için ayrı ayrı useState tanımlama, URL'den okuma, değeri ayrıştırma, bir onChange veya onClick olayında router.push() veya router.replace() ile URL'yi güncelleme işlemleri tekrarlanır. Bu, kod tekrarına yol açar.
3. Reaktivite ve Senkronizasyon Zorlukları: Uygulama state'i ile URL arasındaki senkronizasyonu manuel olarak sağlamak zordur. Özellikle bir filtre değiştiğinde diğerlerinin de güncellenmesi gerektiğinde, bu süreç hataya açık hale gelir.
4. Performans Endişeleri: Her filtre değişikliğinde router.push() çağırmak, tarayıcı geçmişine çok sayıda giriş ekleyebilir ve performansı olumsuz etkileyebilir. Özellikle arama terimi gibi sık değişen parametrelerde bu durum daha da belirginleşir.

nuqs Çözümü: Temiz ve Güçlü Yönetim

nuqs, bu karmaşık senaryoyu yönetmek için ideal bir araçtır. useQueryStates hook'u ve tip-güvenli ayrıştırıcıları sayesinde, tüm filtreleme parametrelerini tek bir merkezden, temiz ve verimli bir şekilde yönetebiliriz.

nuqs ile Filtreleme Sistemi Uygulaması

Bir ana ürün listeleme bileşenimiz olduğunu ve bu bileşenin içinde çeşitli filtre bileşenlerini barındırdığını düşünelim. Her filtre bileşeni, kendi parametresini nuqs aracılığıyla URL ile senkronize edecektir. Ana sayfamızın (app/products/page.tsx) yapısı aşağıdaki gibi olabilir:

// app/products/page.tsx
'use client'; // Ana sayfa bileşenimiz client tarafında çalışmalı

import { useQueryStates } from 'nuqs';
import { useEffect } from 'react';

// Filtre bileşenlerinin import'ları (aşağıda detaylandırılacak)
import CategoryFilter from '../../components/filters/CategoryFilter';
import PriceRangeFilter from '../../components/filters/PriceRangeFilter';
import BrandFilter from '../../components/filters/BrandFilter';
import SortFilter from '../../components/filters/SortFilter';
import SearchInput from '../../components/filters/SearchInput';
import PaginationControls from '../../components/filters/PaginationControls';

interface Product {
  id: number;
  name: string;
  category: string;
  price: number;
  brand: string;
  // Diğer ürün özellikleri
}

// Mock ürün verisi
const allProducts: Product[] = [
  { id: 1, name: 'Akıllı Telefon X', category: 'Elektronik', price: 12000, brand: 'Marka A' },
  { id: 2, name: 'Kablosuz Kulaklık Y', category: 'Elektronik', price: 1500, brand: 'Marka B' },
  { id: 3, name: 'Dizüstü Bilgisayar Z', category: 'Elektronik', price: 25000, brand: 'Marka A' },
  { id: 4, name: 'T-Shirt M', category: 'Giyim', price: 250, brand: 'Marka C' },
  { id: 5, name: 'Kot Pantolon N', category: 'Giyim', price: 500, brand: 'Marka D' },
  { id: 6, name: 'Roman Kitabı A', category: 'Kitap', price: 75, brand: 'Yayınevi E' },
  { id: 7, name: 'Tablet P', category: 'Elektronik', price: 8000, brand: 'Marka B' },
  { id: 8, name: 'Akıllı Saat Q', category: 'Elektronik', price: 3000, brand: 'Marka A' },
];

const ITEMS_PER_PAGE = 3;

export default function ProductListingPage() {
  const [{ categories, priceMin, priceMax, brands, sort, search, page }, setAllFilters] = useQueryStates({
    categories: { parseAs: 'array(string)', defaultValue: [] },
    priceMin: { parseAs: 'number', defaultValue: 0 },
    priceMax: { parseAs: 'number', defaultValue: 50000 },
    brands: { parseAs: 'array(string)', defaultValue: [] },
    sort: { parseAs: 'string', defaultValue: 'newest' },
    search: { parseAs: 'string', defaultValue: '', debounce: 300 }, // Arama için debouncing
    page: { parseAs: 'number', defaultValue: 1 },
  });

  // Filtrelenmiş ürünleri hesaplama (gerçekte bu sunucuda veya bir API çağrısıyla yapılır)
  const filteredProducts = allProducts.filter(product => {
    // Kategori filtrelemesi
    const categoryMatch = categories.length === 0 || categories.includes(product.category);

    // Fiyat aralığı filtrelemesi
    const priceMatch = product.price >= (priceMin || 0) && product.price <= (priceMax || 50000);

    // Marka filtrelemesi
    const brandMatch = brands.length === 0 || brands.includes(product.brand);

    // Arama terimi filtrelemesi
    const searchTermMatch = (search === '' || product.name.toLowerCase().includes((search || '').toLowerCase()));

    return categoryMatch && priceMatch && brandMatch && searchTermMatch;
  }).sort((a, b) => {
    // Sıralama
    if (sort === 'price_asc') return a.price - b.price;
    if (sort === 'price_desc') return b.price - a.price;
    return 0; // 'newest' veya varsayılan sıralama
  });

  // Paginasyon için ürünleri bölme
  const totalPages = Math.ceil(filteredProducts.length / ITEMS_PER_PAGE);
  const startIndex = ((page || 1) - 1) * ITEMS_PER_PAGE;
  const paginatedProducts = filteredProducts.slice(startIndex, startIndex + ITEMS_PER_PAGE);

  useEffect(() => {
    // Filtreler veya sayfa değiştiğinde logla veya veri çek
    console.log('URL filtreleri güncellendi:', { categories, priceMin, priceMax, brands, sort, search, page });
    // Gerçek bir uygulamada, burada sunucudan yeni filtrelenmiş ürünleri çekmek için bir API çağrısı yapardınız.
  }, [categories, priceMin, priceMax, brands, sort, search, page]);

  return (
    

      

      

        
Ürünler ({filteredProducts.length} adet)
        

          {paginatedProducts.length > 0 ? (
            paginatedProducts.map(product => (
              

                
{product.name}
                
Kategori: {product.category}
                
Marka: {product.brand}
                
Fiyat: {product.price} TL
              
            ))
          ) : (
            
Seçilen filtrelere uygun ürün bulunamadı.
          )}
        
         setAllFilters({ page: p })} />
      
    
  );
}

Yukarıdaki ProductListingPage bileşeni, useQueryStates kullanarak tüm filtre parametrelerini tek bir noktada tanımlar. Her bir filtre için parseAs ve defaultValue ayarları, tip güvenliğini ve başlangıç durumlarını garanti eder. SearchInput için debounce seçeneği kullanılarak gereksiz URL güncellemeleri engellenir. Şimdi, bu ana bileşenin kullandığı alt filtre bileşenlerinin nasıl görünebileceğine dair bazı örnekler:

// components/filters/CategoryFilter.tsx
'use client';
import React from 'react';

interface CategoryFilterProps {
  currentCategories: string[];
  setCategories: (categories: string[]) => void;
  allCategories: string[];
}

const CategoryFilter: React.FC = ({ currentCategories, setCategories, allCategories }) => {
  const toggleCategory = (category: string) => {
    setCategories(
      currentCategories.includes(category)
        ? currentCategories.filter((c) => c !== category)
        : [...currentCategories, category]
    );
  };

  return (
    

      
Kategoriler
      {allCategories.map((cat) => (
        
           toggleCategory(cat)}
            style={{ marginRight: '5px' }}
          />
          {cat}
        
      ))}
    
  );
};

export default CategoryFilter;

// components/filters/PriceRangeFilter.tsx
'use client';
import React from 'react';

interface PriceRangeFilterProps {
  currentMin: number;
  currentMax: number;
  setPriceRange: (min: number, max: number) => void;
}

const PriceRangeFilter: React.FC = ({ currentMin, currentMax, setPriceRange }) => {
  const handleMinChange = (e: React.ChangeEvent) => {
    setPriceRange(Number(e.target.value), currentMax);
  };

  const handleMaxChange = (e: React.ChangeEvent) => {
    setPriceRange(currentMin, Number(e.target.value));
  };

  return (
    

      
Fiyat Aralığı
      
      -
      
    
  );
};

export default PriceRangeFilter;

(Diğer filtre bileşenleri de benzer şekilde, ana ProductListingPage'den aldığı prop'larla setAllFilters fonksiyonunu çağırarak URL'deki ilgili parametreleri güncelleyecektir.)

Vaka Analizinin Faydaları

• Merkezi Yönetim: Tüm filtre parametreleri useQueryStates ile ana bileşende merkezi olarak tanımlanır. Bu, kodun daha düzenli ve anlaşılır olmasını sağlar.
• Tip Güvenliği: TypeScript ve nuqs'un parseAs özelliği sayesinde, categories her zaman bir string[], priceMin/priceMax her zaman bir number olarak ele alınır. Bu, geliştirme sırasında potansiyel hataları ortadan kaldırır.
• Gelişmiş Kullanıcı Deneyimi: shallow routing (varsayılan olarak useQueryStates tarafından yapılır) sayesinde, kullanıcılar filtreleri değiştirdikçe sayfa yenilenmez. debounce özelliği ile arama terimi girişinde gereksiz güncellemeler engellenir. Kullanıcılar URL'yi paylaşabilir ve aynı filtreli sayfayı doğrudan açabilir.
• Daha Az Boilerplate: Manuel URL ayrıştırma, serileştirme ve router.push() çağrılarından kurtulunur. Bu, geliştirme süresini kısaltır ve kodun bakımını kolaylaştırır.

Bu vaka analizi, nuqs'un Next.js'te karmaşık URL parametre yönetimi gerektiren durumlar için ne kadar güçlü ve pratik bir çözüm sunduğunu açıkça göstermektedir. Geliştiriciler, kütüphanenin sunduğu soyutlama sayesinde iş mantığına daha fazla odaklanabilir ve URL yönetimi karmaşasıyla uğraşmaktan kurtulabilirler.

Sonuç: nuqs ile Temiz ve Güçlü URL Yönetiminin Geleceği

Next.js uygulamalarında URL arama parametrelerini yönetmek, geleneksel yaklaşımlarla genellikle karmaşık, hataya açık ve geliştirici deneyimini olumsuz etkileyen bir süreç olmuştur. Ancak nuqs kütüphanesi, bu alanda adeta bir devrim niteliğinde bir çözüm sunarak, URL'leri uygulamanızın tip-güvenli, reaktif ve yönetilebilir bir parçası haline getiriyor. Bu makale boyunca, nuqs'un kurulumundan temel ve ileri düzey kullanımlarına, tip güvenliğinden performans optimizasyonlarına ve gerçek dünya senaryolarına kadar birçok yönünü detaylıca inceledik.

nuqs'un sunduğu useQueryState ve useQueryStates gibi hook'lar, React'ın useState modelinden esinlenerek geliştiricilere tanıdık ve sezgisel bir API sunar. Otomatik tip çıkarımı ve özel ayrıştırıcılar sayesinde, URL'den okunan verilerin doğru tiplerde olmasını garanti altına alırken, gereksiz manuel dönüştürme işlemlerinden kurtulursunuz. Debouncing ve shallow routing gibi özellikler ise, hem uygulamanızın performansını artırır hem de kullanıcı deneyimini zenginleştirir. Özellikle e-ticaret sitelerindeki gelişmiş filtreleme sistemleri gibi karmaşık senaryolarda nuqs, kod tekrarını azaltarak, okunabilirliği artırarak ve hata olasılığını düşürerek geliştiricilere büyük kolaylıklar sağlar.

Next.js ekosisteminde, nuqs URL parametre yönetimi için tercih edilen modern bir standart olma potansiyeli taşımaktadır. Hem App Router hem de Pages Router ile uyumlu olması, güçlü TypeScript desteği ve minimal yapılandırma gereksinimi, onu her ölçekten Next.js projesi için ideal bir seçim haline getiriyor. Sonuç olarak, nuqs sadece bir kütüphane değil, aynı zamanda URL yönetimini düşünme ve uygulama biçimimizde bir ilerlemedir. Uygulamalarınızda temiz, güçlü ve kullanıcı dostu URL'ler oluşturmak istiyorsanız, nuqs listenizin başında yer almalıdır.

Sıkça Sorulan Sorular (SSS)

nuqs sadece App Router ile mi çalışır?

Hayır, nuqs hem Next.js'in yeni App Router yapısı hem de Pages Router yapısı ile tamamen uyumludur. App Router'da client component'lerinizde 'use client' direktifi ile, Pages Router'da ise standart React component'lerinizde kullanabilirsiniz. Server component'lerde doğrudan hook kullanamasanız da, searchParams prop'unu kullanarak ilk değerleri besleyebilir ve client component'lerinizde nuqs'u kullanmaya devam edebilirsiniz.

nuqs kullanmak performansı etkiler mi?

Hayır, doğru kullanıldığında nuqs performansı olumsuz etkilemez. Aksine, manuel URL yönetimi ve router.push() çağrılarına kıyasla daha optimize ve kontrol edilebilir güncellemeler sunar. Özellikle debounce seçeneği ile gereksiz ve sık URL güncellemelerini engelleyebilir, shallow: true ile de tam sayfa yenilemeleri yerine daha hızlı client-side navigasyonlar sağlayabilirsiniz. nuqs, tarayıcı geçmişine yapılan girişleri de mümkün olduğunca optimize eder.

URL'deki bir parametreyi tamamen kaldırmak için ne yapmalıyım?

Bir URL parametresini tamamen kaldırmak için ilgili setQueryState fonksiyonunu null veya undefined değeriyle çağırmanız yeterlidir. Örneğin, setSearchTerm(null) çağrısı, URL'deki q parametresini kaldıracaktır. Eğer useQueryStates kullanıyorsanız, parametre nesnesinde kaldırmak istediğiniz anahtara null veya undefined değeri atayabilirsiniz.

nuqs, Next.js'in kendi useSearchParams'ından ne kadar farklı?

Next.js'in yerleşik useSearchParams hook'u, URL'deki arama parametrelerini yalnızca okumak için tasarlanmıştır ve bir değer atamak veya değiştirmek için doğrudan bir setter fonksiyonu sunmaz. Parametreleri değiştirmek için useRouter ile programatik navigasyon yapmanız gerekir. nuqs ise hem okuma hem de yazma işlevselliği sunar; tıpkı useState gibi bir [value, setter] çifti sağlar. Ayrıca, tip güvenliği, otomatik ayrıştırma/serileştirme, debouncing, custom parser'lar ve birden fazla parametreyi tek seferde yönetme gibi ileri düzey özelliklerle geliştirici deneyimini önemli ölçüde zenginleştirir.

Karmaşık JSON objelerini URL'de saklayabilir miyim?

Evet, nuqs'un createParser fonksiyonunu kullanarak özel bir JSON parser'ı tanımlayabilirsiniz. Bu parser, JavaScript objelerini JSON.stringify() ile bir string'e dönüştürüp URL'ye ekler ve URL'den okurken JSON.parse() ile geri objeye çevirir. Ancak, URL'lerin boyutu sınırlı olduğundan çok büyük veya sık değişen JSON objeleri için URL yerine localStorage veya sunucu tarafı bir depolama yöntemi kullanmak daha iyi bir çözüm olabilir.