Prevent Waterfall Chains in API Routes
Install this skill
npx skills add vercel-labs/agent-skillsWorks across Claude Code, Cursor, Codex, Copilot & Antigravity
API routes frequently suffer from latency bottlenecks when asynchronous operations are executed sequentially. By default, developers often await functions one after another, forcing the server to wait for the completion of an identity check before initiating database queries or external configuration fetches. This approach wastes idle CPU cycles and inflates response times. Preventing waterfall chains involves initiating independent asynchronous tasks as promises immediately, effectively allowing them to overlap in their execution time. By triggering multiple requests simultaneously rather than blocking on each individual call, you reduce total latency to the duration of the longest request rather than the sum of all requests. This technique specifically targets Next.js API routes and Server Actions, optimizing data fetching patterns and ensuring that resource-heavy operations run concurrently whenever dependencies allow.
When to Use This Skill
- •Fetching user session data and global app configurations simultaneously
- •Executing concurrent database queries that do not depend on each other
- •Optimizing server actions that call multiple microservices or external APIs
- •Managing independent side effects during API route processing
How to Invoke This Skill
Example prompts that trigger this skill in Claude Code, Cursor, or Antigravity:
- “Optimize my API route latency
- “Stop sequential database queries in my Server Action
- “Fix waterfall requests in Next.js
- “How do I run fetch calls in parallel?
- “Reduce total response time for this endpoint
What this skill does
- •Initiates multiple asynchronous requests concurrently without waiting
- •Uses Promise.all for batching independent operations
- •Improves server-side latency in Next.js endpoints
- •Identifies overlapping dependencies versus blocking chains
- •Reduces total request execution time by overlapping I/O wait times
When not to use it
- ✕When a second operation requires a value returned from the first
- ✕When hitting rate-limited APIs where concurrent requests trigger blocks
- ✕When operations involve shared mutable state that requires strict ordering
Example workflow
- Identify blocked calls in your API route or Server Action
- Assign asynchronous functions to variables without the await keyword
- Await the primary dependency if one exists
- Group subsequent independent promises into a single Promise.all call
- Return the combined data result to the client
Prerequisites
- –Basic understanding of JavaScript Promises
- –Experience with Next.js API Routes or Server Actions
Pitfalls & limitations
- !Over-parallelizing operations that depend on sequential database states
- !Running into third-party API rate limits by sending too many requests at once
- !Difficulty debugging stack traces when multiple promises fail simultaneously
FAQ
How it compares
While manual implementation requires careful promise management, this pattern provides a structured, predictable way to avoid block-wait-block loops, whereas generic prompts often fail to account for specific dependency ordering.
📄 Full skill instructions — original source: vercel-labs/agent-skills
In API routes and Server Actions, start independent operations immediately, even if you don't await them yet.
**Incorrect (config waits for auth, data waits for both):**
export async function GET(request: Request) {
const session = await auth()
const config = await fetchConfig()
const data = await fetchData(session.user.id)
return Response.json({ data, config })
}**Correct (auth and config start immediately):**
export async function GET(request: Request) {
const sessionPromise = auth()
const configPromise = fetchConfig()
const session = await sessionPromise
const [config, data] = await Promise.all([
configPromise,
fetchData(session.user.id)
])
return Response.json({ data, config })
}For operations with more complex dependency chains, use
better-all to automatically maximize parallelism (see Dependency-Based Parallelization).How to Use This Skill Unit
Option A: Project-Specific (Recommended)
- Click "Download" above
- In your project, create the directory:
.agent/skills/async-api-routes/ - Save the file as
SKILL.md - The agent will automatically discover the skill based on its description.
Option B: Global Installation (All Agents)
Save the file to these locations to make it available across all projects:
- Claude Code:
~/.claude/skills/vercel-labs/agent-skills/async-api-routes/SKILL.md - Cursor:
~/.cursor/skills/vercel-labs/agent-skills/async-api-routes/SKILL.md - Antigravity:
~/.gemini/antigravity/skills/vercel-labs/agent-skills/async-api-routes/SKILL.md
🚀 Install with CLI:npx skills add vercel-labs/agent-skills
