Skip to main content

Async Api Routes

Source: .agents/references/coding-standard/vercel-react-best-practices/rules/async-api-routes.md

Metadata​

  • title: Prevent Waterfall Chains in API Routes
  • impact: CRITICAL
  • impactDescription: 2-10× improvement
  • tags: api-routes, pages-api, waterfalls, parallelization

Content​

This repo: Pages Router only — apply to src/pages/api/ handlers (NextApiRequest / NextApiResponse). Server Actions are not used here.

Prevent Waterfall Chains in API Routes​

In pages/api handlers, start independent operations immediately, even if you don't await them yet.

Incorrect (config waits for auth, data waits for both):

import type { NextApiRequest, NextApiResponse } from 'next'

export default async function handler(req: NextApiRequest, res: NextApiResponse) {
  const session = await auth(req)
  const config = await fetchConfig()
  const data = await fetchData(session.user.id)
  return res.status(200).json({ data, config })
}

Correct (auth and config start immediately):

import type { NextApiRequest, NextApiResponse } from 'next'

export default async function handler(req: NextApiRequest, res: NextApiResponse) {
  const sessionPromise = auth(req)
  const configPromise = fetchConfig()
  const session = await sessionPromise
  const [config, data] = await Promise.all([
    configPromise,
    fetchData(session.user.id)
  ])
  return res.status(200).json({ data, config })
}

For operations with more complex dependency chains, use better-all to automatically maximize parallelism (see Dependency-Based Parallelization).