Next.js API Type Validation Enhancement

[Undertone0809]

Goals

1. Provide a simple, type-safe API validation mechanism that leverages TypeScript interfaces for runtime validation
2. Enable automatic type sharing between frontend and backend to ensure API contract consistency
3. Reduce validation boilerplate while supporting both simple and complex validation scenarios

Non-Goals

1. Replace or compete with full-featured validation libraries like Zod, Yup, or Joi
2. Provide comprehensive schema transformation capabilities beyond basic type validation
3. Address authentication, authorization, or other security concerns beyond input validation

Background

Currently, Next.js does not provide a built-in solution for API request/response validation. Developers typically rely on one of these approaches:

1. Manual validation: Writing custom validation logic for each API endpoint, which is error-prone and results in significant boilerplate code
2. Third-party libraries: Using libraries like Zod, Yup, or Joi, which require additional setup and may be overkill for simple validation needs
3. tRPC: Some developers adopt tRPC for end-to-end typesafe APIs, but this requires a significant architectural shift and may not be suitable for all projects
   While these approaches work, they all have drawbacks:

• Manual validation is repetitive and error-prone
• Third-party libraries add complexity and bundle size
• TypeScript interfaces are not enforced at runtime
• No built-in mechanism ensures API implementations match their TypeScript definitions
• Type sharing between client and server requires manual synchronization

This feature would bridge the gap between simple TypeScript interfaces and full validation libraries, providing a lightweight, built-in solution that leverages the TypeScript type system while adding runtime validation. It would integrate seamlessly with Next.js's API routes, supporting both the simple use cases (with just TypeScript interfaces) and more complex validation scenarios (with Zod or similar libraries).

Similar approaches have been successfully implemented in other frameworks like NestJS (with class-validator) and Fastify (with JSON Schema), demonstrating the value of built-in validation that aligns with the framework's design philosophy.

Proposal

Next.js API Type Validation Enhancement Proposal

Current Problems

1. Lack of Built-in Type Validation

   • Next.js API routes lack built-in type validation mechanisms, leading to type errors only discovered at runtime
   • TypeScript interfaces are only effective during compilation and cannot guarantee data conformity at runtime
   • Developers must implement manual validation logic or integrate third-party libraries

2. Frontend-Backend Type Disconnection

   • API request and response type definitions aren't automatically shared between client and server
   • API contract changes require manual type updates in multiple places
   • No mechanism to ensure API implementations match their TypeScript definitions

3. Validation Boilerplate

   • Developers write repetitive validation code for each API endpoint
   • Validation error handling lacks standardization

Proposed Solution

1. Simplified Validation with TypeScript Types

// Simplified API type validation
import { typedHandler } from 'next/api';

// Using TypeScript interfaces to define request and response types
interface CreateUserRequest {
  name: string;
  email: string;
  age?: number;
}

interface CreateUserResponse {
  id: string;
  createdAt: string;
}

// Simple type validation
export const POST = typedHandler<CreateUserRequest, CreateUserResponse>(
  async (req) => {
    // req.body is already validated and typed as CreateUserRequest
    const userData = await req.json();
    
    // Business logic...
    
    return Response.json({
      id: "123",
      createdAt: new Date().toISOString()
    });
  }
);

2. Zod Support for Complex Validation

// Complex validation scenarios
import { typedHandler } from 'next/api';
import { z } from 'zod';

// Using Zod for complex validation
const UserSchema = z.object({
  name: z.string().min(2),
  email: z.string().email(),
  age: z.number().int().positive().optional()
});

type CreateUserRequest = z.infer<typeof UserSchema>;
type CreateUserResponse = { id: string; createdAt: string };

export const POST = typedHandler<CreateUserRequest, CreateUserResponse>({
  // Optional advanced validation configuration
  validation: {
    schema: UserSchema,
    errorHandler: (errors) => {
      return Response.json({ errors }, { status: 400 });
    }
  }
})(async (req) => {
  const userData = await req.json();
  
  // Business logic...
  
  return Response.json({
    id: "123",
    createdAt: new Date().toISOString()
  });
});

3. Support for Different Request Parts

// Support for validating different parts of the request
import { typedHandler } from 'next/api';

interface GetUserQuery {
  id: string;
}

interface GetUserResponse {
  name: string;
  email: string;
}

export const GET = typedHandler<never, GetUserResponse, GetUserQuery>(
  async (req) => {
    // req.query is already validated and typed
    const { id } = req.query;
    
    // Business logic...
    
    return Response.json({
      name: "John Doe",
      email: "[email protected]"
    });
  }
);

4. Automatic Type Sharing

// Auto-generated client types
import { ApiTypes } from '@/app/api/users/types';

// Client-side usage
const createUser = async (userData: ApiTypes['POST']['request']) => {
  const response = await fetch('/api/users', {
    method: 'POST',
    body: JSON.stringify(userData)
  });
  
  const result: ApiTypes['POST']['response'] = await response.json();
  return result;
};

5. Simple Global Configuration

// next.config.js
module.exports = {
  apiValidation: {
    // Default validation behavior
    defaultValidation: 'runtime', // 'runtime' | 'compile-time' | 'none'
    // Default error format
    errorFormat: {
      status: 400,
      structure: { success: false, errors: [] }
    },
    // Generate API type definition files
    generateTypes: true
  }
}

Implementation Strategy

1. Type Inference Middleware: Develop a lightweight middleware based on TypeScript types
2. Runtime Type Checking: Implement basic runtime type checking, supporting both simple types and complex validation
3. Type Generation: Automatically generate type definitions that can be shared between client and server
4. Progressive Adoption: Allow developers to adopt gradually, without forcing migration of all APIs at once

Benefits

1. Simplified API: For simple scenarios, only TypeScript interfaces are needed
2. Flexibility: Complex validation scenarios can use Zod or other validation libraries
3. Type Safety: Ensure API implementations match their type definitions
4. Developer Experience: Reduce boilerplate code, improve development efficiency
5. Standardized Error Handling: Unified error response format

Usage Example Comparison

Current Approach:

// Currently requires manual validation
export async function POST(req: Request) {
  try {
    const body = await req.json();
    
    // Manual validation
    if (!body.name || typeof body.name !== 'string') {
      return Response.json({ error: 'Invalid name' }, { status: 400 });
    }
    if (!body.email || typeof body.email !== 'string') {
      return Response.json({ error: 'Invalid email' }, { status: 400 });
    }
    
    // Business logic...
    
    return Response.json({ id: '123', createdAt: new Date().toISOString() });
  } catch (error) {
    return Response.json({ error: 'Invalid request' }, { status: 400 });
  }
}

Proposed Approach:

import { typedHandler } from 'next/api';

interface UserRequest {
  name: string;
  email: string;
}

interface UserResponse {
  id: string;
  createdAt: string;
}

export const POST = typedHandler<UserRequest, UserResponse>(async (req) => {
  const userData = await req.json();
  // userData is already validated as UserRequest type
  
  // Business logic...
  
  return Response.json({
    id: '123',
    createdAt: new Date().toISOString()
  });
});

[zahinafsar]

You can try https://www.npmjs.com/package/next-ts-api, which makes your existing Next.js API route fully typesafe. MORE

Example Route:

import { NextApiRequest } from 'next-ts-api';

// POST /api/todos
export async function POST(
  request: NextApiRequest<{
    title: string;
  }>
) {
  const { title } = await request.json();
  const newTodo: Todo = {
    id: Math.random().toString(),
    title,
    completed: false
  };
  return NextResponse.json(newTodo);
}

API Call:

import { createNextFetchApi } from "next-ts-api";
import { type ApiRoutes } from "../types/next-ts-api"; // auto generated
 
export const api = createNextFetchApi<ApiRoutes>();

const response = await api('todos', { // type-safe API route
    method: 'POST',
    body: {
      title: "New Todo" // type-safe body
    } 
});
const newTodo = await response.json(); // type-safe return data