async-api-routes — Claude Code rule: what it does, how to install
async-api-routes prevents sequential waterfall requests in API routes and Server Actions. It instructs the assistant to launch independent promises immediately rather than chaining awaits.
MIT ★ 7,191 updated 2026-10-24
.claude/rules/async-api-routes.mdWhat async-api-routes does
The rule targets backend endpoints where standalone tasks wait unnecessarily behind unrelated awaits. It enforces starting independent async calls right away: session checks and configuration fetches trigger side by side, synchronizing later via Promise.all.
For complex dependency trees, the rule suggests adopting better-all to schedule tasks automatically. If your project avoids extra packages, you will have to wire those multi-step dependencies by hand with standard promises.
What it helps with
- eliminate waterfall awaits in route handlers
- run auth checks and config loading in parallel
- speed up Server Actions response times
- restructure nested async calls with Promise.all
Example prompts for the agent
- Refactor this API route to eliminate async waterfalls
- Check our Server Actions for sequential awaits on independent data
- Update this GET handler so config loads alongside the session check
How to install async-api-routes
Manually: put the files in place
.claude/rules/async-api-routes.mdThe paths frontmatter field limits the files
AGENTS.md
Codex reads AGENTS.md: paste the rule text there
Manually: put the files in place
.cursor/rules/async-api-routes.mdcFrontmatter: description, globs, alwaysApply
Manually: put the files in place
.github/instructions/async-api-routes.instructions.mdThe applyTo field sets which files it applies to
Manually: put the files in place
.devin/rules/async-api-routes.mdManually: put the files in place
.clinerules/async-api-routes.mdStep by step, with commands for each platform: AGENTS.md vs CLAUDE.md: what they are and which one to use
Questions about async-api-routes
How to install async-api-routes in Claude Code?
Add the instruction file to your project at .claude/rules/async-api-routes.md.
What does async-api-routes do?
It stops sequential await calls on independent operations inside API routes. The agent initiates independent promises immediately and resolves them using Promise.all.
What is recommended for complex dependency chains?
For multi-tiered asynchronous tasks, the rule suggests using better-all to organize parallel execution based on dependencies.
Source text
async-api-routes.md · MIT
---
title: Prevent Waterfall Chains in API Routes
impact: CRITICAL
impactDescription: 2-10× improvement
tags: api-routes, server-actions, waterfalls, parallelization
---
## Prevent Waterfall Chains in API Routes
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):**
```typescript
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):**
```typescript
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).
© tech-leads-club · MIT · tech-leads-club/agent-skills