Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/dev0302/nextjs-project-1/llms.txt

Use this file to discover all available pages before exploring further.

This endpoint lets clients verify whether a desired username is available before submitting the full sign-up form. It validates the input against the usernameSchema Zod rules and, if the format is valid, queries MongoDB to check for an existing document with that username.

​
Method and URL

GET /api/check-username-unique?username={username}
Authentication: None required.

​
Query Parameters

​
username
string
required
The username to check for availability. Must be 2–20 characters long and contain only letters (a-z, A-Z), digits (0-9), or underscores (_).

​
Validation Rules

The value is parsed by usernameSchema (defined in src/app/schemas/signUpSchema.ts) before any database query is made:
RuleConstraintError message
Minimum length2 characters"Username must be atleast 2 characters"
Maximum length20 characters"username must not be more than 20"
Allowed characters/^[a-zA-Z0-9_]+$/"Username can only contain letters, numbers, and underscores"

​
Responses

All responses share the ApiResponse shape: 
interface ApiResponse {
  success: boolean;
  message: string;
}

​
200 — Username available

The username passed validation and no matching document was found in MongoDB. 
{
  "success": true,
  "message": "Username available"
}

​
200 — Username taken

The username passed validation but is already registered in the database. 
{
  "success": false,
  "message": "Username already exists"
}

​
400 — Invalid format

The value failed Zod validation. The message field contains the first validation error. 
{
  "success": false,
  "message": "Username must be atleast 2 characters"
}

​
401 — Server error

An unexpected error occurred while connecting to the database or running the query. 
{
  "success": false,
  "message": "Error while validating username uniqueness"
}
Both the “available” and “taken” outcomes return HTTP 200. Always inspect the success boolean in the response body — do not rely on the status code alone to determine availability.

​
Response Fields

​
success
boolean
true if the username is available; false if it is already taken, failed validation, or an error occurred.
​
message
string
Human-readable description of the outcome. Mirrors the Zod error text verbatim when validation fails.

​
Example Request

curl "http://localhost:3000/api/check-username-unique?username=alice"
Available response: 
{
  "success": true,
  "message": "Username available"
}
Taken response: 
{
  "success": false,
  "message": "Username already exists"
}
Invalid format response: 
{
  "success": false,
  "message": "Username must be atleast 2 characters"
}

​
How It Works

  1. The handler extracts username from req.url via new URL(req.url).searchParams.
  2. The raw value is wrapped in { username } and passed to UsernameQuerySchema.safeParse().
  3. If parsing fails, the first Zod issue’s message is returned immediately with a 400 status — no database call is made.
  4. On a valid parse, dbConnect() establishes (or reuses) the MongoDB connection and User.findOne({ username }) is executed.
  5. If a document is found the endpoint returns { success: false, message: "Username already exists" }; otherwise { success: true, message: "Username available" } — both with status 200.

​
Usage in the UI

The sign-up form calls this endpoint as an onChange handler while the user types their desired username, providing real-time availability feedback without waiting for full form submission. 
// Debounced onChange handler inside the sign-up form
useEffect(() => {
  const checkUsername = async () => {
    if (username.length < 2) return;
    const res = await fetch(
      `/api/check-username-unique?username=${encodeURIComponent(username)}`
    );
    const data = await res.json();
    setUsernameMessage(data.message);
    setUsernameAvailable(data.success);
  };
  checkUsername();
}, [username]);

Build docs developers (and LLMs) love

Get started for freeTalk to us