route handler

[near shoal]

difference between Request, NextRequest, NextApiRequest

[balmy bolt]

Hi @near shoal. I'm kapa.ai, your friendly support bot. I will try to answer your question by searching through the knowledge base. :wave:

---

In Next.js, the types Request, NextRequest, and NextApiRequest are used in different contexts for handling incoming HTTP requests. Here’s how they differ:

---

1. Request

• What it is: The standard Web Request API, part of the Fetch API.
• Where used: Used in Route Handlers in the App Router (files like app/api/route.ts).
• Features: Provides access to request properties like url, method, headers, and body methods (json(), text(), etc.).
• Example:

  export async function GET(request: Request) {
    // Use request.url, request.headers, etc.
  }
  

• Reference: Route Handlers

---

2. NextRequest

• What it is: An extension of the standard Web Request API, provided by Next.js.
• Where used: Used in Middleware and Route Handlers in the App Router.
• Features: Adds Next.js-specific helpers, such as:
  • cookies for reading/mutating cookies
  • nextUrl for easier URL and query parameter handling
• Example:

  import type { NextRequest } from 'next/server'
  
  export async function GET(request: NextRequest) {
    const query = request.nextUrl.searchParams.get('query')
    const token = request.cookies.get('token')
  }
  

• Reference: NextRequest API, Route Handler Examples

---

3. NextApiRequest

• What it is: A type provided by Next.js for API Routes in the Pages Router.
• Where used: Used in files under pages/api/ (API Routes).
• Features: Based on Node.js’s http.IncomingMessage, with Next.js-specific additions for easier access to query, body, cookies, etc.
• Example:

  import type { NextApiRequest, NextApiResponse } from 'next'
  
  export default function handler(req: NextApiRequest, res: NextApiResponse) {
    // Use req.query, req.body, req.cookies, etc.
  }
  

• Reference: API Routes

---

Summary Table:

Type	Used In	Based On	Special Features
Request	App Router (Route Handlers)	Web Fetch API	Standard web API
NextRequest	Middleware, App Router	Web Fetch API	Next.js helpers (cookies, URL)
NextApiRequest	Pages Router (API Routes)	Node.js IncomingMessage	Next.js helpers (query, body)

---

If you need to choose, use:

• Request/NextRequest in the App Router (Route Handlers, Middleware)
• NextApiRequest in the Pages Router (API Routes)

Route Handlers
NextRequest API
API Routes

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

@near shoal Kapa.ai is still learning and improving, please let me know how I did by reacting below.

[near shoal]

@balmy bolt
For app router,
how to know when request is closed

[balmy bolt]

Let me check the knowledge base for you again. Give me one moment! :books:

---

In the Next.js App Router, when using Route Handlers (e.g., in files like app/api/route.ts), the request object is based on the standard Web Fetch API. Unlike the Node.js API (used in Pages Router API routes), the Fetch API's Request object does not provide a direct way to listen for connection closure or aborted requests.

However, if you are deploying on Vercel and using the Node.js runtime, Vercel Functions allow you to detect cancelled (aborted) requests by listening for the error event on the request object. In this context, you must explicitly end the response when a request is cancelled to avoid the function hanging or timing out. Here’s an example from the Vercel documentation:

import { VercelRequest, VercelResponse } from '@vercel/node';
 
export default async (request: VercelRequest, response: VercelResponse) => {
  let cancelled = false;
  request.on('error', (error) => {
    if (error.message === 'aborted') {
      console.log('request aborted');
    }
    cancelled = true;
  });

  response.writeHead(200);

  for (let i = 1; i < 5; i++) {
    if (cancelled) {
      response.end();
      return;
    }
    response.write(`Count: ${i}\n`);
    await new Promise((resolve) => setTimeout(resolve, 1000));
  }

  response.end('All done!');
};

This approach is only available in the Node.js runtime, not in the default Edge runtime or standard Fetch API route handlers in the App Router Cancelled Requests.

If you are using the standard App Router route handlers (with the Fetch API), there is currently no documented way in the official Next.js docs to detect when a request is closed or aborted by the client. If you need this functionality, you may need to use the Node.js runtime and the Vercel-specific APIs as shown above.

Summary:

• In the App Router with the default Fetch API, there is no built-in way to detect when a request is closed.
• In the Node.js runtime on Vercel, you can listen for the error event on the request object to detect cancellations, but you must end the response manually Cancelled Requests.

---

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon: