DEV Community: Nana Okamoto

Stop Manually Managing URLSearchParams in Next.js — Use nuqs Instead

Nana Okamoto — Fri, 13 Mar 2026 14:03:48 +0000

Modern web applications often represent UI state in the URL.

For example:

search filters
pagination
sorting
tab selection
dashboard parameters

A typical URL might look like this:

/products?category=books&sort=price&page=2

Synchronizing UI state with the URL improves several things:

shareability (users can share filtered views)
bookmarking
browser navigation
predictable application state

However, implementing this in Next.js App Router often leads to repetitive and fragile code.

Recently I started using a library called nuqs, and it significantly improved the developer experience when managing URL state.

In this article I'll cover:

why managing query parameters manually is painful
why I chose nuqs
how to use it in real projects
what improved in my development workflow

The Problem: Manual URL State Management

Without a helper library, managing URL state usually requires combining:

useSearchParams
useRouter
URLSearchParams
useState
useEffect

Example:

'use client'

import { useRouter, useSearchParams } from 'next/navigation'
import { useState, useEffect } from 'react'

export default function ProductFilter() {
  const router = useRouter()
  const searchParams = useSearchParams()

  const [category, setCategory] = useState(
    searchParams.get('category') || ''
  )

  useEffect(() => {
    const params = new URLSearchParams(searchParams)
    params.set('category', category)

    router.push(`?${params.toString()}`)
  }, [category])

  return (
    <select
      value={category}
      onChange={(e) => setCategory(e.target.value)}
    >
      <option value="">All</option>
      <option value="books">Books</option>
      <option value="games">Games</option>
    </select>
  )
}

While this works, it introduces several problems.

Problems ⚡️

• Boilerplate code everywhere
• Manual parsing of URLSearchParams
• Hard to scale with multiple filters
• Easy to introduce bugs
• No built-in type safety

As applications grow (for example search pages or dashboards), this logic quickly becomes hard to maintain.

What Is nuqs?

nuqs is a lightweight library that treats URL query parameters as React state.
Instead of manually synchronizing state and the URL, you simply use a hook.
Conceptually:

URL Query <-> React State

This drastically simplifies query parameter management.

Installing nuqs

npm install nuqs

That's it.

The Same Example Using nuqs

Here is the same filter example rewritten with nuqs.

'use client'

import { useQueryState } from 'nuqs'

export default function ProductFilter() {
  const [category, setCategory] = useQueryState('category')

  return (
    <select
      value={category ?? ''}
      onChange={(e) => setCategory(e.target.value)}
    >
      <option value="">All</option>
      <option value="books">Books</option>
      <option value="games">Games</option>
    </select>
  )
}

The URL automatically updates when the state changes.

Example result:

/products?category=books

Compared to the manual implementation:

no router logic
no useEffect
no manual query parsing

Type-Safe Query Parameters

One of the most powerful features of nuqs is its parser system.
Example: pagination.

import { useQueryState, parseAsInteger } from 'nuqs'

const [page, setPage] = useQueryState(
  'page',
  parseAsInteger.withDefault(1)
)

Benefits:

page is always a number
default value is 1
invalid query values are handled safely

This prevents many runtime bugs.

Managing Multiple Query Parameters

Complex UIs usually have multiple filters.
nuqs handles this cleanly using useQueryStates.

import { useQueryStates, parseAsString } from 'nuqs'

const [filters, setFilters] = useQueryStates({
  category: parseAsString,
  sort: parseAsString
})

Updating the filters:

setFilters({
  category: 'books',
  sort: 'price'
})

Resulting URL:

?category=books&sort=price

This keeps filter logic predictable and easy to maintain.

Why I Chose nuqs

When selecting a library for URL state management, I considered several factors.

1. Developer Experience

nuqs removes the need to manually synchronize state and the URL.

Instead of managing useEffect, URLSearchParams, and router updates, query parameters behave like React state.

This dramatically reduces boilerplate and improves readability.

2. Type Safety

The parser system allows query parameters to be typed.
This ensures predictable values and reduces runtime errors in TypeScript projects.

3. Zero Dependencies and Lightweight

Another reason I chose nuqs is that it has zero runtime dependencies.
This is important for several reasons:

smaller bundle size
fewer potential security vulnerabilities
lower risk of dependency conflicts
easier long-term maintenance

In modern frontend projects, dependency trees can grow quickly.
Using focused libraries with minimal dependencies helps keep applications lean.

nuqs follows this philosophy very well.

4. Designed for Modern Next.js

nuqs integrates naturally with Next.js App Router and React hooks.
It fits well into modern React architectures without introducing additional complexity.

Real Impact in My Project

After introducing nuqs, several improvements became clear.

Less Boilerplate
Query state logic became significantly smaller and easier to understand.

Better Maintainability
Adding new filters now requires only a few lines.

Fewer Bugs
Type-safe parsing prevents invalid query states.

Better UX
Because the UI state lives in the URL:

filters can be shared
pages can be bookmarked
browser navigation works naturally

When nuqs Is Especially Useful

From my experience, nuqs works especially well for:

search/filter pages
e-commerce listings
dashboards
analytics tools
pagination systems
sorting UIs

In other words:
✨ any interface where UI state should be reflected in the URL.

Final Thoughts

Managing URL state manually in Next.js often leads to repetitive and fragile code.

nuqs provides a clean abstraction that treats query parameters as React state while keeping everything type-safe and lightweight.

For modern React and Next.js applications, it can significantly improve both:

developer experience
code maintainability

If you're building filter-heavy interfaces or dashboards, I highly recommend giving nuqs a try!

Implementing Push Notifications with Next.js and Firebase Cloud Messaging

Nana Okamoto — Mon, 28 Apr 2025 06:54:10 +0000

Push notifications are a powerful way to engage users and bring them back to your application. In this tutorial, we'll implement push notifications in a Next.js application using Firebase Cloud Messaging (FCM). We'll cover setting up Firebase, configuring permissions, and handling notifications in both foreground and background states.

Note: This guide is based on Next.js 15 or later. Ensure your project uses this version to follow along.

Prerequisites

Basic knowledge of TypeScript and Next.js
A Firebase account
Node.js installed on your machine

Step 1: Configure Firebase in Your Project

First, create a new Firebase project:

Go to the Firebase Console
Create a new project (or use an existing one)
Add a web app to your project
Install the Firebase SDK in your Next.js project:

npm install firebase

Create a firebase-config.ts file in your project to configure Firebase:

// firebase-config.ts
import { initializeApp } from "firebase/app";
import { getMessaging, getToken, onMessage } from "firebase/messaging";

const firebaseConfig = {
  apiKey: process.env.NEXT_PUBLIC_FIREBASE_API_KEY,
  authDomain: process.env.NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN,
  projectId: process.env.NEXT_PUBLIC_FIREBASE_PROJECT_ID,
  storageBucket: process.env.NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET,
  messagingSenderId: process.env.NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID,
  appId: process.env.NEXT_PUBLIC_FIREBASE_APP_ID,
};

let messaging: ReturnType<typeof getMessaging>;

if (typeof window !== "undefined" && "navigator" in window) {
  const app = initializeApp(firebaseConfig);
  messaging = getMessaging(app);
}

export { messaging, getToken, onMessage };

Step 2: Setting Up Service Worker

Firebase Cloud Messaging requires a service worker to handle background notifications. Create a file called firebase-messaging-sw.js in your public directory:

// firebase-messaging-sw.js
importScripts(
  "https://www.gstatic.com/firebasejs/10.11.1/firebase-app-compat.js"
);
importScripts(
  "https://www.gstatic.com/firebasejs/10.11.1/firebase-messaging-compat.js"
);

const firebaseConfig = {
  apiKey: "YOUR_API_KEY",
  authDomain: "YOUR_AUTH_DOMAIN",
  projectId: "YOUR_PROJECT_ID",
  storageBucket: "YOUR_STORAGE_BUCKET",
  appId: "YOUR_MESSAGING_SENDER_ID",
  messagingSenderId: "YOUR_APP_ID",
};

firebase.initializeApp(firebaseConfig);

const messaging = firebase.messaging();

messaging.onBackgroundMessage((payload) => {
  const notificationTitle = payload.notification.title;
  const notificationOptions = {
    body:
      payload.notification.body,
      icon: payload.notification.icon,
    data: { url: payload.fcmOptions?.link || "/" },
  };

  self.registration.showNotification(notificationTitle, notificationOptions);
});

self.addEventListener("notificationclick", (event) => {
  event.notification.close();
  const targetUrl = event.notification.data?.url || "/";

  event.waitUntil(
    clients
      .matchAll({
        type: "window",
        includeUncontrolled: true,
      })
      .then((clientList) => {
        for (const client of clientList) {
          if (client.url.includes(targetUrl) && "focus" in client) {
            return client.focus();
          }
        }
        return clients.openWindow(targetUrl);
      })
  );
});

Important Note: You should not use environment variables in the service worker file as it's served directly by the browser. For production, you would need to implement a build step that replaces these values.

Step 3: Request Notification Permission

1. Requesting Permission

Request user permission for push notifications, as explicit consent is required. If needed, save the retrieved token to your database within this function.

// requestNotificationPermission.ts
import { getToken, messaging } from "./firebase";

export const requestNotificationPermission = async () => {
  try {
    const permission = await Notification.requestPermission();

    if (permission !== "granted") {
      return;
    }

    const registration = await navigator.serviceWorker.register(
      "/firebase-messaging-sw.js"
    );

    if (!registration) {
      return;
    }

    const token = await getToken(messaging, {
      vapidKey: process.env.NEXT_PUBLIC_FIREBASE_VAPID_KEY,
      serviceWorkerRegistration: registration,
    });

    if (!token) {
      return;
    }

    // Save the Token to a Database here if you need

  } catch (error) {
    console.error("Error Requesting Notification Permission:", error);
    return;
  }
};

2. Creating a Notification Component

To handle incoming notifications elegantly, create a dedicated Notification Permission component:

// components/NotificationPermission.tsx
"use client";

import { useEffect } from "react";
import { requestNotificationPermission } from "@/lib/firebase/requestNotificationPermission";

const NotificationPermission = () => {

  useEffect(() => {
    const subscribeUser = async () => {
        await requestNotificationPermission(user.id);
      };

    subscribeUser();
  }, []);

  return null;
};

export default NotificationPermission;

3. Adding the Notification Component

Integrate the Notification component into your application layout to ensure it is always active:

// layout.tsx
import NotificationPermission from "@/components/notification/NotificationPermission";
...

export default function RootLayout({
  children,
}: Readonly<{
  children: React.ReactNode;
}>) {
  return (
    <html lang="en">
      <body>
        <NotificationPermission/>
        {children}
      </body>
    </html>
  );
}

Step 4: Adding the firebase-admin.json

In order to send notifications from your server, you will need to integrate Firebase Admin SDK. This requires adding the firebase-admin.json configuration file to your project.

Go to the Firebase Console.
Under Project Settings > Service Accounts, generate a new private key.
Download the key file, which is named firebase-admin.json.
Place the firebase-admin.json file in your project’s root or a secure folder.

Now, you’ll need to install the firebase-admin package:

npm install firebase-admin

Finally, configure Firebase Admin SDK to use this file by adding the following code to your backend:

// firebaseAdmin.ts
import admin from "firebase-admin";
import settings from "../../../config/firebase-admin.json";

const serviceAccount = settings as admin.ServiceAccount;

if (!admin.apps.length) {
  try {
    admin.initializeApp({
      credential: admin.credential.cert(serviceAccount),
    });
    console.log("Firebase Admin Initialized Successfully");
  } catch (error) {
    console.error("Firebase Admin Initialization Failed:", error);
  }
}

export default admin;

Step 5: Sending Notifications via Firebase Admin SDK

Add the following function to handle sending notifications:

// sendNotification.ts
import admin from "@/lib/firebase/firebaseAdmin";

interface Recipient {
  endpoint: string;
}

export const sendNotification = async (
  title: string,
  body: string,
  recipients: Recipient[]
) => {
  try {
    const response = await admin.messaging().sendEachForMulticast({
      tokens: recipients.map((recipient) => recipient.endpoint),
      notification: { title, body },
    });

    console.log(
      `Notification sent! Success: ${response.successCount}, Failures: ${response.failureCount}`
    );

    if (response.failureCount > 0) {
      response.responses.forEach((res, index) => {
        if (
          !res.success &&
          res.error?.code === "messaging/registration-token-not-registered"
        ) {
          console.warn(`Invalid token found: ${recipients[index].endpoint}`);
        }
      });
    }
  } catch (error) {
    console.error("Error sending notifications:", error);
  }
};

Step 6: Creating the Notification API

To send notifications programmatically, you need an API endpoint. Create an API route in your Next.js application:

// pages/api/notifications/route.ts
import { NextRequest, NextResponse } from "next/server";
import { sendNotification } from "@/lib/firebase/sendNotification";

export async function POST(req: NextRequest) {
  try {
    const body = await req.json();

    const { title, body, recipients } = body;

    if (!title || !body || !recipients) {
        return NextResponse.json(
          { success: false, message: "Missing required fields" },
          { status: 400 }
        );
    }

    await sendNotification(title, body, recipients);
    return res.status(200).json({ message: "Notification sent successfully" });

  } catch (error) {
    console.error("Error sending notification:", error);
    res.status(500).json({ error: "Failed to send notification" });
  }
}

To call this API, send a POST request to /api/notifications with a JSON body containing the title, body, and recipients. The title and body should be strings, and recipients should be an array of FCM tokens.

Step 7: Environment Setup

Ensure that you add the required environment variables:

// .env.local
NEXT_PUBLIC_FIREBASE_API_KEY=your-api-key
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=your-project.firebaseapp.com
NEXT_PUBLIC_FIREBASE_PROJECT_ID=your-project-id
NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET=your-project.appspot.com
NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=your-sender-id
NEXT_PUBLIC_FIREBASE_APP_ID=your-app-id
NEXT_PUBLIC_FIREBASE_VAPID_KEY=your-vapid-public-key

Get the first 6 variables from your Firebase Console: All of these can be found under Project Settings > General.
Get a VAPID key from the Web configuration section in Firebase Console > Project Settings > Cloud Messaging under "Web Push certificates."

⚠️ Security Considerations

When working with push notifications, always keep the following in mind:

Never expose your Firebase Admin SDK credentials in client-side code
Store environment variables securely
Implement proper validation and authentication for your notification API
Consider rate limiting to prevent abuse

Conclusion

By setting up Firebase Cloud Messaging (FCM) with Web Push notifications in Next.js, you’ve enabled an effective way to engage your users in real-time. However, always stay mindful of security best practices, keep an eye on evolving web push standards, and regularly check Firebase documentation for new updates and features.

Simplifying Authentication in React Applications with Clerk

Nana Okamoto — Fri, 29 Nov 2024 02:03:10 +0000

User authentication is essential for web applications.
While working on my personal food delivery app project , I needed a secure and easy-to-integrate solution, and that’s when I discovered Clerk. It’s a powerful, customizable authentication library that works seamlessly with React. Clerk offers simple sign-up/sign-in, OAuth, and social logins.

In this article, I’ll share how I integrated Clerk into my React application, how quickly I got it up and running, and why I believe it’s an excellent choice for authentication　for individual developers.

Why Clerk?

When I started researching authentication solutions, I was overwhelmed by the variety of options available. Many tools offered flexibility but required significant setup and maintenance. Then, I found Clerk, which stood out for its:

Ease of use: Clerk provides prebuilt components for sign-in, sign-up, and user profile management that integrate seamlessly into React.
Security: Clerk handles sensitive authentication flows, such as token management and session storage, adhering to modern security best practices.
Developer focus: Its detailed documentation and intuitive API reduce the learning curve.

Setting Up Clerk in a React App

Setting up Clerk was a breeze. Here’s a quick overview of how I added it to my React application:

Step 1: Sign up and create a Clerk project

Start by creating a new project in Clerk's dashboard.
During setup, as shown in the screenshot below, you can immediately set your service name and choose authentication methods, making customization quick and easy. Once created, you’ll get API keys and a frontend API URL for integration.

Step 2: Install Clerk package

npm install @clerk/clerk-react

After installing the package, set up the required environment variables.
The VITE_CLERK_PUBLISHABLE_KEY can be obtained from the Clerk dashboard

VITE_CLERK_PUBLISHABLE_KEY=YOUR_PUBLISHABLE_KEY

Step 3: Configure ClerkProvider

Wrap your application with the ClerkProvider component, which provides the necessary context for authentication.

import React from 'react'
import ReactDOM from 'react-dom/client'
import App from './App.tsx'
import './index.css'
import { ClerkProvider } from '@clerk/clerk-react'

const PUBLISHABLE_KEY = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY

if (!PUBLISHABLE_KEY) {
  throw new Error('Add your Clerk publishable key to the .env.local file')
}

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <ClerkProvider publishableKey={PUBLISHABLE_KEY} afterSignOutUrl="/">
      <App />
    </ClerkProvider>
  </React.StrictMode>,
)

Step 4: Add Sign-In and Sign-Up Components to the Header

Let's integrate Clerk components into your app's Header.
In this example, we’ll use Clerk's <SignedIn> and <SignedOut> components.

<SignedIn> renders its children only when the user is logged in.
<SignedOut> renders its children only when no user is logged in.

import { SignedIn, SignedOut, RedirectToSignIn, UserButton } from "@clerk/clerk-react";

const Header = () => {
  return (
    <header>
      <h1>My App</h1>
      <nav>
        <SignedIn>
          {/* Display the UserButton when logged in */}
          <UserButton />
        </SignedIn>
        <SignedOut>
          {/* Redirect to Sign-In when no user is logged in */}
          <RedirectToSignIn />
        </SignedOut>
      </nav>
    </header>
  );
};

export default Header;

Step 5: Protect Routes

You can restrict access to certain routes based on the user’s authentication status.

import { useAuth } from '@clerk/clerk-react';  
import { Navigate } from 'react-router-dom';  

const ProtectedPage = () => {  
  const { isSignedIn } = useAuth();  

  if (!isSignedIn) {  
    return <Navigate to="/sign-in" />;  
  }  

  return <div>...</div>
};  

export default ProtectedRoute;

What Else Can Clerk Do?

Clerk offers a lot more to enhance your app’s authentication system:

OAuth & Social Logins: Easily integrate logins with providers like Google, GitHub, and Twitter.
Multi-Factor Authentication (MFA): Add an extra layer of security with SMS or authentication apps.
Passwordless Authentication: Use magic links or one-time passcodes for a smoother user experience.
User Profiles: Customize and manage user profiles with additional fields.
Role-Based Access Control (RBAC): Restrict or grant access to features based on user roles.
Webhooks: Automate workflows with webhooks for events like sign-ups or profile updates.

Why Clerk for Solo Developers?

Clerk is a game-changer for solo developers. It requires minimal setup and lets you focus on building core features while handling the complexities of user authentication and security. I implemented a fully functional login system in under an hour, saving me time.

Conclusion

Clerk simplifies authentication in React applications by providing a fast, secure, and customizable solution. Whether you’re building a small app or a larger platform, Clerk offers everything you need to implement a robust authentication system without hassle.

References:

📕 Clerk Documentation