DEV Community: DevUnionX

5 Things Even AI Can’t Do: Context, Creativity, and Human Touch in Node/NestJS Development

DevUnionX — Fri, 17 Jul 2026 22:40:32 +0000

MY GAME JUST LAUNCHED

Flip Duel: Online Card Game - Apps on Google Play

1v1 card duel! Bluff, beat your rival. Combine your cards, raid the dungeon!

play.google.com

Introduction

AI is powerful and getting smarter – it can generate code, answer questions, and even help design systems. Yet seasoned engineers know there are tasks only people can do. A recent industry overview bluntly states: “it does not understand meaning… it cannot create independent judgment… [and] it lacks emotional intelligence”. In other words, AI excels at narrow, data-driven tasks but fails where true understanding, empathy, or accountability is required. This article – aimed at Node.js/NestJS developers and engineers – digs into five such areas. Each section explains the concept, provides real-world dev examples (with code snippets in JavaScript/TypeScript when relevant), and notes where AI helps and where it stumbles. We cite the latest research and official docs to back up these points. By the end, you’ll have a grounded perspective on AI-assisted development: how to benefit from code generation tools and LLMs while knowing when human judgment must step in.

1. AI Can’t Truly Understand Context

AI models do a fantastic job spotting patterns in data and text, but real context remains elusive. LLMs process words based on statistical associations, not on meaning the way humans do. As one AI analyst notes, “AI… operates by detecting patterns in historical data. It does not understand meaning. It does not know consequences”. In practice, that means an LLM won’t “get” the broader situation behind your code or data. It has no sense of what happened a minute ago in the team standup or what business rules apply to a request.

Context in Software Systems

Consider NestJS’s ExecutionContext, which provides metadata about a request or event handler. In a HTTP context, a guard or interceptor can see exactly which controller and method are handling the request. For example, Nest’s docs show that when handling a POST to CatsController.create(), getHandler() returns the create() function and getClass() returns CatsController. This allows the code to adapt behavior based on context:

@Injectable()
export class LoggingInterceptor implements NestInterceptor {
  intercept(context: ExecutionContext, next: CallHandler) {
    const httpCtx = context.switchToHttp();
    const req = httpCtx.getRequest<Request>();
    console.log(`Incoming ${req.method} ${req.url}`);  
    console.log(`Handler: ${context.getClass().name}.${context.getHandler().name}`);
    return next.handle();
  }
}

Here, the developer explicitly uses runtime context (HTTP request, handler info) to log or branch logic. An AI given only a code snippet and a prompt might not infer all those details about when and how the code executes. It lacks true awareness of the request lifecycle and runtime state.

Where AI Excels and Falls Short

Modern LLMs can “remember” recent conversation (via a context window) and even long documents. For example, Google’s Gemini can handle over a million tokens. But larger windows aren’t a magic fix: as the Anthropic team points out, “LLMs, like humans, lose focus… as the number of tokens in the context window increases, the model’s ability to recall information decreases”. This “context rot” means that even if you feed the AI pages of documentation, it may still get confused about which part is relevant to the current query.

In practice, developers use Retrieval-Augmented Generation (RAG) to mitigate this. RAG fetches specific data from external sources into the prompt. As NVIDIA explains, RAG “enhances the accuracy and reliability of generative AI models with information from specific and relevant data sources”. In other words, you build a “knowledge base” (say, your own code docs) and include facts in the prompt. This helps ground the AI’s answers. NVIDIA even notes that RAG “reduces the possibility that a model will give a very plausible but incorrect answer, a phenomenon called hallucination”.

For example, in Node.js you might write a simple RAG function to answer questions about your project:

async function answerWithRAG(query, vectorStore) {
  const docs = await vectorStore.retrieveRelevant(query);  // fetch related docs
  const prompt = `
    Use the following information to answer the question.
    ${docs.join("\n")}
    Q: ${query}
    A:
  `;
  const completion = await openai.createChatCompletion({
    model: "gpt-4",
    messages: [{ role: "user", content: prompt }]
  });
  return completion.data.choices[0].message.content;
}

Here the code explicitly retrieves context (docs from a vector store) and injects it into the prompt. The AI no longer has to recall everything; it sees targeted context. This improves reliability but also highlights AI’s gap: it needed human help (the vector store, curation of docs) to supply true context. AI by itself would likely hallucinate or miss important facts without that.

Lessons for Developers

Use prompt and context engineering: Carefully craft prompts, provide relevant docs, and manage the token window. Treat context as finite. Anthropic advises thinking “in context” – iteratively curating only the smallest set of high-signal tokens needed for the task.
Validate outputs: Even with RAG or careful prompting, always test AI-generated code or answers against known facts. The AI might produce fluent but incorrect text once you exceed its context capacity.
Combine AI with logic: Use static types, unit tests, and logging (as in the NestJS example) to catch context mismatches early. AI can suggest code, but you must check it in the full system context.

In summary, AI struggles with hidden context and system state. It can automate low-level coding, but developers must manage broader context, architecture and integration – tasks that require human insight.

2. AI Can’t Take Responsibility

AI will help write the code or suggest a design, but it won’t own the results. Machines don’t have accountability or intention. A recent discussion on AI accountability emphasizes: “it cannot assume responsibility for the outcomes of those decisions… The emphasis must remain on ensuring that humans are equipped and willing to take accountability”. In other words, if an AI-driven system causes a bug, outage, or even an ethical breach, the responsibility ultimately falls on the human developers, operators, or managers involved.

Real-World Software Example

Imagine deploying a NestJS microservice that uses an AI to classify user inputs. If the AI misclassifies sensitive data, who fixes it? Engineers must detect it, debug the model or logic, and apologize to stakeholders – tasks no AI can do. Similarly, an AI-generated pull request still requires a developer to review, merge, and be ready to revert if things go wrong.

Consider DevOps and CI/CD: AI tools can suggest pipeline configurations or even generate Kubernetes YAMLs. But when a deployment fails or a security issue emerges, a human is on-call to investigate and respond, not the AI. If the pipeline says “build succeeded” but a hidden error slipped through, the engineer digs into logs and patches the code.

The need for human oversight is often summed up: “you can outsource execution; you can’t outsource consequences. If it goes wrong, 'AI said so' won’t save you”. (An Instagram quote puts it simply: accountability cannot be automated – and in a production system, someone must own every decision.)

AI’s Strengths vs. Weaknesses (Accountability)

Aspect	AI Role (Strength)	Limitation (Responsibility)
Decision Support	Generates options and analysis rapidly	Cannot endorse or guarantee outcomes; doesn’t understand ethics
Consistency	Follows rules consistently in code generation	Lacks judgment; blindly follows flawed instructions without question
Speed	Suggests fixes or configs in seconds	May miss context that a human would catch; not liable for mistakes

As the Lumenalta report on AI limits notes, “high-stakes work still depends on judgment about tradeoffs, ambiguity, and consequences. AI can support that work. It will not own it well.”. AI can accelerate the “explore” phase (e.g., propose database schemas or microservice structures), but the final decision (“commit” phase) remains human-led.

Lessons for Developers

Always review and test: Never merge AI-generated code or configs unreviewed, especially for critical paths. Pair AI with code reviews, automated tests, and staging deployments.
Human-in-the-loop: Design systems so that important decisions (security, product priorities, unusual conditions) require a human sign-off. As one AI executive advises: “treat outputs as hypotheses, keep decision-making human-led”.
Clear ownership: In agile teams, use clear ownership or responsibility matrices. Document which team/person is responsible for each AI-assisted component. This way, when an issue arises, it doesn’t become “AI’s fault,” it’s traceable to the responsible owner.

By acknowledging that AI isn’t accountable, teams avoid the trap of over-reliance. AI is a tool that suggests – but we, the developers and architects, must decide and own the results.

3. AI Can’t Replace Human Creativity

AI can recombine existing code patterns in novel ways, but it does not originate new ideas with intent the way developers and designers do. It might surprise you with an unusual code snippet, but that’s remixing what it “saw” during training. As one expert pithily puts it, “AI recombines patterns. Humans create with purpose, emotion, and narrative.”.

Creativity in Software Engineering

Consider a developer brainstorming a new feature or user story. They think of product vision, user needs, and constraints. They sketch architectures, whiteboard ideas, and iterate. AI can help flesh out details – for instance, suggesting class structures or API endpoints – but it cannot conceive the original vision or the “why” behind the feature.

For example, writing a complex Node.js application often involves creative design: deciding the right microservices boundaries, naming conventions, or novel algorithms. An AI model can suggest code snippets (like a clever function), but it doesn’t understand the problem domain. It doesn’t know your startup’s unique value proposition or the UX story your frontend needs. It only knows patterns.

One way to see this is how AI deals with unexpected situations. The Lumenalta analysis gives a marketing use case: AI can generate campaign variants and test subject lines quickly. The same system will not recognize that a market shift makes the campaign premise wrong, or that a customer reaction signals a brand risk that historical data cannot capture. The AI is excellent at extending existing patterns, but it “does not originate a better frame on its own.” It takes a human to see beyond the data and pivot creatively.

Even in coding, creativity shows up in choosing algorithms or patterns. Given two approaches, an engineer might innovate a hybrid or use domain knowledge. AI will tend to use common design patterns. It might suggest a decorator or service for a NestJS app, but it won’t invent a brand-new architecture style or fix a deep UX issue in ways never documented.

AI’s Strengths vs. Weaknesses (Creativity)

Capability	AI Strength	Limitation
Code Generation	Generates boilerplate and known patterns fast	Lacks original intent or problem framing
Problem Solving	Offers multiple solution variants	Doesn’t understand when to break the mold
Innovation	Can suggest combinatorial recombinations	“Surprising output” comes from scale, not true novel ideas

In fact, a data scientist notes that the common saying “AI can’t be creative – it only recombines what already exists” has truth, but also nuance. Modern LLMs with huge context windows can produce surprisingly novel-seeming outputs (thanks to exploring massive combinatorial spaces). But those surprises are still rooted in the training data, not some internal “imagination.”

Lessons for Developers

Focus AI on repetitive creativity: Let AI handle rote creativity tasks (e.g. generating code templates, unit test stubs, or design variations). For truly open-ended innovation, rely on human brainstorming.
Use AI to augment, not replace design: For example, ask an LLM to propose NestJS service names or database schema from a docstring – it can speed things up. But always vet them: humans must ensure these proposals fit the product’s unique needs.
Break down big problems: If AI suggestions seem “stuck,” break the task into smaller parts. Then use your own creativity for the overall structure and let AI assist with the details.

By embracing that creativity is ultimately human, teams can use AI to rapidly prototype and experiment, while reserving the “big idea” work for developers’ insight.

4. AI Can’t Build Genuine Human Relationships

No matter how friendly a chatbot sounds, it isn’t a human colleague or friend. Machines lack authentic empathy, trust, and emotional intelligence. As a therapist writes, AI “aids with facts but lacks emotional depth and intuition. Professionals offer empathy and care that AI cannot replicate.”. In software teams, this means AI cannot truly motivate developers, resolve interpersonal conflicts, or mentor junior engineers.

Team and Customer Context

On a project, relationships matter. A senior developer encourages a newcomer, understands frustration, and adapts feedback to their learning style. An AI code reviewer might suggest changes, but it won’t pick up on a dev’s confusion or morale. It can’t shake hands, share a joke, or build trust after a deployment outage. In DevOps incidents, an on-call engineer consoles stakeholders, while AI tools only log errors.

In customer-facing systems (like chatbots), scripted “compassion” is limited. A customer unhappy with a bug needs understanding; an AI response can sound polite, but it doesn’t actually feel urgency or remorse. If a chatbot just repeats instructions, the user feels unheard. Real human support engineers will empathize and maybe go the extra mile. This reflects the Psychology Today point that “genuine connection… [from AI] is missing” – when people use digital support, “the missing piece? Real connection”.

AI’s Strengths vs. Weaknesses (Relationships)

Aspect	AI Role (Strength)	Limitation (Relationships)
User Engagement	Can handle routine queries quickly	Lacks true empathy; misses unspoken cues
Team Support	Provides answers or suggestions 24/7	Cannot inspire, trust, or genuinely motivate
Social Interaction	Can mimic friendly tone in text	Has no self, no genuine care or understanding

Rafiq Wayani, a leadership coach, lists candidly that “AI cannot build relationships: Business is still built on trust… No algorithm can replicate genuine human connection”. In other words, while AI can simulate conversation, it can’t feel the emotional currents between people. It won’t notice if a team member is anxious, nor remember a manager’s leadership style to tailor its output.

Lessons for Developers

Use AI for tasks, but invest in people skills: Let chatbots handle FAQs or generate resource links, freeing time for your team to focus on empathetic communication and collaboration.
Preserve human contact points: For example, in customer support, use AI to draft responses but have a human review them. Or use AI to process logs and let engineers do the actual user outreach.
Build trust in processes: When adopting AI tools (like Copilots or code reviews), be transparent. Don’t promise the AI understands your code; instead say it offers suggestions. This way developers feel in control, maintaining trust in the tool.

Ultimately, AI can aid productivity and consistency, but the “glue” of any engineering effort remains human relationships and trust. Machines support us; people support each other.

5. AI Can’t Decide What Should Be Built

Perhaps most fundamentally: AI can’t decide the vision. It doesn’t know your users’ deepest needs, your company’s mission, or which product idea will really move the needle. No matter how much data it has, it can’t set priorities or conceive what to build first.

Strategic Decision-Making

In startup or product work, deciding what to build involves strategy, ethics, and foresight – “dirty work” beyond data patterns. Craig Sullivan summarizes it: “No LLM is going to tell you which deal to prioritize… or when a prospect needs a human conversation instead of another automated touchpoint… Treat outputs as hypotheses, keep decision-making human-led”. For example, an LLM can analyze customer feedback for topics, but it won’t know that shifting market trends mean the feedback signals a new feature idea. Only human product managers with market context can interpret that.

In system architecture, this shows up too. AI might generate microservice code or suggest a database (OK for boilerplate), but choosing between architectural paradigms (e.g. REST vs. GraphQL, monolith vs. microservices) requires understanding team skills, legacy constraints, and future roadmap. AI lacks that broader perspective and cannot weigh the trade-offs beyond statistical patterns.

Where AI Helps and Falls Short

AI is great at the exploration phase of problem solving – generating lots of ideas or code variants. But it’s weak at convergence. As one engineer puts it, “LLMs are great at divergence (getting more ideas), and weak at convergence (picking the right one).” Even with large-scale outputs, picking the best solution relies on human context: team culture, performance constraints, and politics.

For example, RAG or agents can gather and summarize information to inform a decision – they scale knowledge. But they won’t say “build this feature because we’ll capture X market.” They lack business acumen and on-ground insight. An LLM might suggest moving a block of code to a new file; it cannot suggest building a whole new component because “Team A is overworked, and Team B has expertise.”

Lessons for Developers

Keep humans in the loop for vision: Always have senior engineers or product owners steer the high-level roadmap. Use AI to gather data or simulate user scenarios, then decide the plan yourself.
Use AI as a tool, not a boss: When an AI suggests many solutions, treat them as hypotheses. Score them using metrics you care about and choose with human judgment.
Invest in domain expertise: Your knowledge of customers, business, and technical debt are irreplaceable. As one summary reminds us: “Jobs evolve. Judgment does not disappear.”.

In short, AI can never replace the creative spark and responsibility of deciding what to build. It lacks purpose. That means it’s up to the team to set direction and ensure technology serves human goals.

Key Takeaways

Context is limited: LLMs handle text in isolation and have finite memory (context window). Use techniques like RAG to inject relevant data, and always test AI-generated code in the full system context.
AI is assistive, not accountable: AI can generate code or suggestions, but it cannot own mistakes or make judgment calls. Human engineers must review outputs and bear responsibility.
Creativity stays human: AI recombines patterns at scale but does not innovate with intent. Use AI for prototyping, but rely on developers for vision and strategy.
Relationships need humans: No matter how “smart,” AI lacks real empathy or emotional intelligence. Preserve human interaction in teamwork and user support.
Humans decide what to build: AI can suggest and explore, but picking the right path requires human judgment and domain knowledge. Treat AI output as hypotheses, not decisions.

Conclusion

AI and LLM tools are reshaping software development – they’re incredibly powerful assistants. They can write boilerplate, suggest fixes, summarize logs, and even generate initial system designs. But they have clear limitations. They don’t understand systems the way we do, they don’t own outcomes, they aren’t truly creative, they can’t form real relationships, and they won’t set the product vision. These aren’t flaws; they’re just the nature of current AI.

As developers, our mission is to harness AI’s strengths while managing its weaknesses. That means leveraging prompt engineering, retrieval systems, and CI/CD pipelines to get the best outputs – while always keeping humans in the loop for testing, oversight, and final decisions. When a chatbot “hallucinates,” or Copilot writes vulnerable code, it’s a reminder that context, responsibility, and human values still require us.

The future is not humans vs AI, but humans with AI. By understanding these five boundaries, we can use AI to accelerate development without losing sight of what only people can do. As one developer put it, AI “accelerates the explore phase; humans own the commit phase”. Remember that rule of thumb, and AI becomes an advantage – not a liability.

Call to Action: Have you encountered situations where an AI’s suggestion went wrong? Or where human judgment caught an AI error? Share your experiences and thoughts in the comments below. Let’s learn from each other about the real-world limits of AI in development.

FAQ

Q: Can AI ever fully replace software developers?

A: Not in the foreseeable future. Current AI lacks true understanding, ethics, and responsibility. It’s best used as a coding assistant. Developers still need to review, integrate, and make judgment calls about AI outputs.

Q: How do we guard against AI “hallucinations” in code?

A: Always validate AI-generated code with tests and type checks. Use retrieval-augmented generation (RAG) and prompt constraints to ground answers. Never trust the AI blindly – treat it as a collaborator, not an oracle.

Q: What is the role of prompt engineering?

A: Prompt engineering helps focus the AI on desired outcomes. By crafting clear, specific prompts (and including context via system messages or RAG), you improve the quality of AI assistance. However, even perfect prompts can’t teach the model empathy or responsibility.

Q: If AI can’t be creative, why do some say it is creative?

A: AI can generate novel-looking combinations because it has seen vast amounts of data. Technically, it’s remixing patterns at scale. Some surprising results can feel creative, but AI doesn’t conceive ideas from first principles or feelings. It lacks intent and can’t do strategic innovation without human guidance.

Q: How should DevOps teams handle AI tools?

A: Treat AI tools (like infrastructure-as-code generators or monitoring bots) as helpers. Use them to automate routine tasks, but maintain human oversight on critical deployment steps. For example, an AI can draft a Kubernetes manifest, but a human must review security settings and verify it in a dev cluster.

Q: Can prompt-based agents (AI that calls APIs and tools) overcome these limitations?

A: Agents can mimic multi-step reasoning and use tools, improving task execution. But they still rely on underlying LLMs. They don’t truly understand business context or own outcomes. They reduce some manual work but raise new concerns (e.g., uncontrolled API usage). Even advanced agents need carefully defined boundaries and human supervision.

Q: How does AI impact architecture and system design?

A: AI can suggest design patterns and even draw diagrams from high-level descriptions, which is useful for brainstorming. But choosing the right architecture (monolith vs microservices, specific frameworks, database technologies) requires weighing long-term factors. AI suggestions should be one input, not a final design, as it won’t know your team’s full constraints and goals.

Feel free to drop additional questions or comments below. We encourage discussion on how to balance AI tools with human expertise in your development workflow!

5 Things AI Cannot Do at Node.js

DevUnionX — Mon, 13 Jul 2026 19:21:28 +0000

Flip Duel: Online Card Game - Apps on Google Play

1v1 card duel! Bluff, beat your rival. Combine your cards, raid the dungeon!

play.google.com

Executive Summary

This report examines five fundamental tasks and limitations that artificial intelligence cannot reliably perform for Node.js developers. AI models generally operate through statistical approaches based on large datasets, which can lead to problems such as factual mismatch (hallucination), loss of context, and security vulnerabilities. For example, an LLM (Large Language Model) may suggest a piece of code that looks attractive but is incorrect or fabricated. In the Node.js context, errors of this kind can create serious problems such as blocking the single-threaded event loop or degrading performance. Throughout the report, we address the causes of each limitation, its impact on Node.js, and the design patterns that can be used to mitigate it. We illustrate these solutions with code examples and architectural diagrams, and we also offer insights into future research trends along with recommended resources. Ultimately, the report emphasizes that in order to maximize the benefits of AI tools, developer oversight, testing, and sound architectural planning remain critically important.

1. Hallucination and Accuracy Problems

Although current AI models produce convincing, template-consistent answers, they provide no guarantee of accuracy. Because LLMs rely on statistical language modeling, they frequently produce the phenomenon known as "hallucination" — that is, they can generate fabricated answers that are entirely inconsistent with the user's request. For example, when given a legal writing assignment, an LLM may produce fabricated citations and unsupported arguments on a topic; similarly, when asked for Node.js code, it may output code containing nonexistent functions, missing parameters, or faulty logic. Hallucinations generally stem from biases or contradictory information in the model's training data. An arXiv study showed that roughly 95% of the errors arising in LLM-assisted code generation were caused by incorrect functionality (failure to meet requirements). This means that when you attempt to produce "production code," you will encounter unexpected errors and unreliable output.

For Node.js developers, this creates two fundamental risks. First, if AI-generated code is used directly, the application may experience functional errors and unexpected crashes. For example, even when AI-assisted code constructs an API request, it may fail to perform proper authentication or parameter validation; or an operation may return an unexpected result. Such code may not even appear to be broken while running, yet the application's business logic breaks down or security vulnerabilities emerge. Second, hallucinations make code harder to maintain. When complex, unnecessary, or unexplainable pieces of code are generated, maintenance becomes more expensive over time and developer productivity declines. The ambiguities contained in AI-generated code require extra testing and review to separate out the real bugs.

Mitigation Approaches: In the Node.js world, there are various approaches to overcoming this problem. First and foremost, AI-generated code must pass through human oversight and be verified with unit tests. Within the code flow, critical outputs can be checked using assertion libraries or a type system (TypeScript). In addition, balancing (prompt engineering) methods can be applied: specifying all necessary context and constraints in detail before the code prompt can reduce the likelihood of hallucination. For example, OpenAI's system message can be used to describe the code environment or fixed variables. A Node.js example is given below:

// Example: AI call (OpenAI API)
import { Configuration, OpenAIApi } from 'openai';
const openai = new OpenAIApi(new Configuration({ apiKey: process.env.OPENAI_KEY }));

async function generateValidatedCode(prompt) {
  // First, provide context by adding a test scenario
  const messages = [
    { role: 'system', content: 'You are a JavaScript expert and must produce only correct, tested code.' },
    { role: 'user', content: prompt }
  ];
  const res = await openai.createChatCompletion({ model: 'gpt-4', messages });
  return res.data.choices[0].message.content;
}

// Usage
const code = await generateValidatedCode('Write a function that adds two numbers.');
console.log(code);

With this approach, the responses coming from the AI can become more reliable in terms of accuracy. Furthermore, with methods similar to Chain of Thought, the AI can be encouraged to evaluate the logical steps of its answers one by one and correct them where necessary. Finally, methods such as Retrieval-Augmented Generation (RAG) — which draw on existing databases or documentation — also reduce the risk of hallucination; when responding to a request, the AI can first consult sources such as a manual or a code repository.

2. Architectural and Performance Reasoning

Node.js's single-threaded event loop architecture provides a major advantage under high I/O-intensive loads, but it introduces architectural constraints for CPU-intensive operations. AI tools generally offer a standard solution when writing code, yet they cannot foresee a Node application's architectural decisions or performance bottlenecks. As noted on the Full Scale blog, AI can code an Express route; however, it cannot recognize that this route contains a blocking file system call, or that it will crash due to a missing await. In other words, AI produces code but cannot analyze that code's effects under real system load. For Node.js developers, this can lead to performance bugs and scalability problems.

For example, when an endpoint runs too slowly, an experienced developer immediately suspects that the event loop is being blocked. But even when an AI model sees a blocking call such as fs.readFileSync in the code, it "cannot understand" the load this will place on the system and may proceed with its recommendation regardless. In such a case, the application struggles to handle all incoming requests at once. Similarly, situations such as a memory leak or an unhandledRejection also cannot be foreseen by AI; these errors only emerge through real production experience and require a human eye.

Effects on Node.js: This limitation leads to the following effects on the architecture of Node.js services:

Single-Threaded Limitation: If any operation blocks the event loop, the entire application slows down. For this reason, synchronous methods should be avoided for critical operations, even in scenarios recommended by AI.
Resource Management: Efficient memory usage is required during large file uploads or multiple concurrent user requests. AI-generated code may overlook this complex flow and backpressure management, which can lead to memory overflows.
Error Recovery and Logging: Understanding the causes of errors that occur in distributed systems is difficult for AI. In Node.js, recovery mechanisms for unexpected shutdowns (e.g., a job queue, restart strategies) rely on developer experience; an LLM cannot foresee these automatically.

Practical Solutions and Design Patterns: To mitigate these problems, developers use the following methods:

Using Threads: CPU-intensive tasks (image processing, video encoding, etc.) should not block the main event loop. Instead, Node.js's worker_threads module can be used. For example, the simple Node.js code below runs a heavy operation in a thread so that the event loop is not blocked:

// worker-pool.js
import { Worker } from 'worker_threads';

export function runHeavyTask(data) {
  return new Promise((resolve, reject) => {
    const worker = new Worker(new URL('./worker-task.js', import.meta.url), { workerData: data });
    worker.once('message', resolve);
    worker.once('error', reject);
  });
}

// worker-task.js
import { parentPort, workerData } from 'worker_threads';
// CPU-intensive computation
const result = computeFibonacci(workerData);
parentPort.postMessage(result);

Using Multiple Processes (Cluster): To take advantage of multiple CPU cores, the Node.js cluster module can be used. This module creates multiple instances (Workers) of the application and distributes incoming requests among them to achieve parallelism. For example:

// cluster-example.js
import cluster from 'node:cluster';
import { availableParallelism } from 'node:os';
import http from 'node:http';

if (cluster.isPrimary) {
  const cores = availableParallelism();
  for (let i = 0; i < cores; i++) {
    cluster.fork();
  }
  cluster.on('exit', (worker) => console.log(`Worker ${worker.process.pid} died`));
} else {
  // Each worker opens its own HTTP server
  http.createServer((req, res) => {
    res.end('Hello World\n');
  }).listen(8000);
}

Stream-Based I/O Processing: When processing large data loads (files, network packets), using the Node.js stream API keeps memory usage constant. For example, to process a file line by line, code like the following can be used:

import { createReadStream } from 'fs';
import readline from 'readline';

async function processLargeFile(path) {
  const fileStream = createReadStream(path);
  const reader = readline.createInterface({ input: fileStream });
  for await (const line of reader) {
    // A small line is processed each time
    handleLine(line);
  }
}

In this way, since the entire file is not loaded into memory, the risk of an out-of-memory overflow decreases. Likewise, large data chains can be built with pipeline and Transform streams.

Performance Testing and Profiling: Rather than using the AI's code suggestions directly, load tests and profiling tools (e.g., clinic.js, V8 profilers) are used to detect and optimize bottlenecks. A Node developer should test an AI-suggested code snippet with these tools before moving it into production.

The patterns above carry developers' hierarchical decision-making abilities (which task should be solved with which method, and what is suitable for whom) beyond the reach of AI. Although AI accelerates coding, the weakest link in the system can only be detected through human oversight. Design quality, the selection of the right asynchronous patterns, and efficient resource usage ultimately remain dependent on developers' expertise.

3. Security and Contextual Knowledge Gaps

AI models are generally trained on publicly available and historical code datasets. However, these datasets often contain outdated or weak security practices. Because AI is fundamentally a statistical model, it learns the most frequently encountered code patterns; yet it has no knowledge of how secure those learned patterns are or whether they conform to an application's specific security requirements. This means that even when it runs seemingly functional code, it will bypass hidden security layers.

For example, an AI tool may fail to add input validation when constructing a SQL query, because it is difficult for it to understand the situations in which input sanitization is required. A study cited above concludes that "AI models generate code without deeply understanding your application's security needs, business logic, or architecture." For a developer, this carries the risk that the generated code may contain injection points (injection, XSS, CSRF, etc.). According to a Veracode report, in 2025, 45% of AI-generated code contained one of the OWASP Top 10 security vulnerabilities. For JavaScript specifically, this rate was reported as 43%.

Possible effects for Node.js developers:

Endpoint Security: AI-assisted code may fail to add proper validation when receiving user data such as req.body on the server side. This leaves the door open to malicious requests. In Node.js applications, libraries such as helmet and express-validator should be used; in addition, encryption/security functions should be manually reviewed.
Dependency Chains: AI may add npm packages for the functionality it needs. However, the owner or version of these packages may contain security vulnerabilities. When adding a new package, the developer should check the transitive (indirect) dependency chain and perform package signature and CVE scanning. Tools that detect library vulnerabilities (Snyk, npm audit, etc.) should be used in the environment.
Personal and Confidential Data: AI models cannot check for the presence of a hardcoded secret or confidential information within the code. If a server key or password has been mistakenly placed inside the code, the AI cannot catch this error. On the developer's side, environment variables and secret-management practices (secret manager) should be adopted.

Mitigation Methods: To overcome this limitation, the following can be done:

Static and Dynamic Security Analysis: All code suggested by AI should be examined with static analysis tools (e.g., ESLint + security rules, SonarQube) and dynamic scans. For example, OpenAI's security code review API or open-source tools can inspect the code. If security tests are integrated into the continuous integration (CI) pipeline, known weaknesses in AI code can be caught in advance.
Security Libraries and Frameworks: Critical operations can be standardized by using security-focused libraries built for Node.js (e.g., express-validator, csurf, or bcrypt). When obtaining output from AI, it is helpful to explicitly request (state in the prompt) that these libraries be used. Whether the code sanitizes user input when receiving it must be checked.
Security in the Software Development Lifecycle (DevSecOps): Adding security after the fact can be difficult when writing code with AI tools. For this reason, threat modeling should be performed at the outset, and the potential attack surfaces should be identified. For example, if a chatbot is being developed, precautions such as reviewing database access queries and adding XSS protection should be planned from the start.
Role-Based Controls: Some decisions require human judgment. For example, for code snippets that require user consent or legal compliance, human intervention should be preferred over an automated solution. AI output can also be run through human-approved security code reviews (peer review).

In general, however much AI accelerates code writing, "automatic convenience" can be a trap when it comes to security. Ensuring flawless security practices is still the job of experienced developers and security specialists. In the Node.js context, only humans can notice and fix the potentially dangerous aspects of code. For this reason, AI code should be treated as a "first draft," and security checks should never be skipped.

4. Lack of Context and Long-Term Memory

Modern LLMs are quite effective within short-term context (the context window), but they have limited memory. A model's context window is bounded by the amount of text it can "remember" at once. For example, GPT-4's context length is not billions of tokens — it is limited. This prevents the model from considering a very long conversation history or a large code repository all at once. In long interactions with a user or in large datasets, the AI may forget information that was passed in an earlier glance.

In a Node.js development environment, this shortcoming is felt in the following situations:

Stateful Context: Cross-process or long-term session information is not retained by the AI. For example, a chatbot that does not know what a user did in previous requests may, over time, forget information it needs to remember. As a solution, Node.js applications should store state in a session store or in databases and re-supply this state to the AI at each interaction.
Project and Code Recall: It is not practical to give an entire large codebase to an AI model. The AI may not remember the specific configurations used in your Node.js project (file paths, custom packages). In this case, it may be necessary to summarize important configuration information (e.g., database schemas) in advance and add it to the input, or to have the AI read part of the project incrementally. Otherwise, the model may make incorrect suggestions by overlooking the current code's dependencies or architecture.

As IBM has noted, an LLM's context window is like "working memory"; if too much information is fed in, the parts that cannot fit into the model are consumed, or must be summarized and passed along. This limits how much information the AI can learn at once. In Node.js services, when there are continuously running long-lived tasks or multi-step workflows, this situation can lead to synchronization problems.

Precautions and Patterns:

Chunking: Breaking long operations into small pieces enables the AI to remember the context in each one. For example, if a large dataset is being processed, a summary query can be made first; the AI is then guided to answer each step incrementally.
Persistent Memory Mechanisms: For information such as conversation history or user preferences, a long-term data storage system can be used. For example, a Node.js application can save user messages to a vector database or a simple database. On the next AI call, the relevant historical information is queried again and added as model input. This is part of the Retrieval-Augmented Generation (RAG) strategy.
Model Updating and Incremental Learning: Some approaches suggest reaching a result without retraining the AI each time by adding a dedicated RAG server or memory layer. For example, it is possible to set up a Node.js API that records user feedback and turn this data into a data source for the project. In the future, giving models the ability to "retain what they learned in a task" is also a research topic.

In short, AI models are limited in terms of short-term memory. Rather than continuously feeding the AI all the information the application needs, Node.js developers should design their systems to keep important state externally and feed it in when needed. This way, both context loss is prevented and the model is spared from information overload.

5. Lack of Creativity and Human Judgment

AI can produce content that appears "creative" to the extent of the data it was trained on; however, it does not possess a genuine capacity for original artistic or conceptual creation. AI draws inferences from templates it has previously seen or been given; it cannot create a solution from scratch, on its own, within an entirely new paradigm. For example, when a design problem or an original algorithmic optimization is required, human creativity still lies beyond AI. As IBM has said, "creativity is still a final frontier for artificial intelligence."

Similarly, AI models lack ethical and emotional reasoning. For instance, a Node.js chatbot may write sentences that appear to offer emotional support to a distressed user, but this is not genuine empathy; the AI does not have the ability to "understand sadness." In decision-support systems or in areas that touch on human matters, human intervention is still required. This situation has the following effects on Node.js development processes:

Design Understanding: AI can make suggestions about code or architecture, but it does not grasp the reasons behind design choices. For example, high-level decisions such as why a microservice architecture should be preferred, or that an endpoint is actually unnecessary, do not come from AI. This kind of strategic "completing the scenario" task relies on human expertise.
Developer Experience and the Human Factor: AI is limited in human-centered matters such as an application's ease of use, workflow design, or user interface. For example, when designing a new API, assessments such as "did this make things harder for the developer to use" are related to human perception. In the Node.js community, an application's fit with teams' workflows is critical — often more so than the technical perfection of the code.
Learning and Adaptation: AI cannot instantly learn from experience and adapt (no incremental learning). A developer, by contrast, can change their code by drawing lessons from problems experienced in a live system. An LLM cannot add this kind of feedback to its own model. Consequently, it requires human analysis again for each new problem.

Precautions: To address this weakness of AI, developers need to reinforce creative thinking and human judgment. AI outputs should be seen as mere suggestions and used as a "decision-support" tool. For example, if a code template is provided, the developer should confirm whether it is appropriate based on their own experience. Simply clarifying questions is also important: before a business requirement description is given to the AI, one should make sure it is fully understood (which in turn requires human communication). Full Scale experts emphasize this point by saying, "reviewing and correcting AI outputs is like the leadership a senior engineer exercises." A Node developer should show the same diligence, questioning the AI's statements with "okay, but is this really correct?"

Comparative Summary Table

Limitation / Task	Impact on Node.js	Solution / Mitigation Approach
Information Hallucination and Accuracy	AI-assisted code may produce incorrect functional results; the burden of readability and maintenance increases.	Code review, unit testing, type checking. Developer oversight and feeding current context via Retrieval. Human-approved vs. automated checks against AI output.
Performance / Event Loop	When the single thread is blocked, the entire Node service slows down; CPU-heavy operations tie up the processor.	Parallelizing heavy workloads with worker_threads or cluster. Processing large data piece by piece with the Stream API.
Security and Privacy	AI code often does not include security checks; it may harbor undetected security vulnerabilities (e.g., XSS, SQL inj.).	Static/dynamic security scanning, code review. Security-focused libraries (express-validator, csurf, etc.). Dependency auditing, version updates.
Context and Long-Term Memory	The LLM's memory limit causes past context to be lost in long conversations or large data processing. Process management becomes outdated.	Storing conversation/session data in a database. Using external memory via Retrieval-Augmented Generation. Feeding the LLM by breaking requests into small pieces.
Creativity / Ethical Judgment	AI cannot produce innovative architectural or design solutions, nor make ethical or emotional decisions. Developer inference is essential.	Design decisions and user experience under human oversight. AI output should always be treated as a "draft." Requirements should be re-examined and human judgment brought in.

Architecture Example Diagram

The mermaid diagram below is an example of a typical architectural pattern showing interaction with an AI service in Node.js applications. Requests from the client are routed to the Node.js API; based on the type of work, the API connects to components such as LLM services, the database, or job queues. Work-intensive tasks are processed in separate services or threads:

flowchart LR
  A[Client Application] --> B[Node.js API Server]
  B --> C[LLM Service]
  B --> D[Database]
  B --> E[Job Queue]
  E --> F[CPU-Heavy Worker]
  C --> D
  style A fill:#D6EAF8,stroke:#1B4F72,stroke-width:2px
  style B fill:#D1F2EB,stroke:#145A32,stroke-width:2px
  style C fill:#F9E79F,stroke:#7D6608,stroke-width:2px
  style D fill:#FADBD8,stroke:#7B241C,stroke-width:2px
  style E fill:#D7BDE2,stroke:#512E5F,stroke-width:2px
  style F fill:#AED6F1,stroke:#154360,stroke-width:2px

In the architecture above, the Node.js API is designed in an asynchronous (non-blocking) manner. Large data jobs are placed onto the Job Queue and processed in parallel by background Worker processes. When AI support is required (e.g., text summarization, analysis), queries are sent to the LLM Service. This service makes a request to the AI model, receives the response, and forwards it to the API. This design prevents a single service from bearing the entire load and provides scalability.

Looking Ahead and Research Directions

In the coming years, many advances are expected in AI technology. Work continues on increasing model context lengths, on long-term memory models, and on enabling AI systems to explain their own decision processes. Researchers are focusing on improving LLMs' real-time learning capabilities and on enhancing secure code generation. For example, chain-of-thought methods reduce hallucinations, while algorithmic learning models may play a role in optimizing code. On the Node.js side, new releases may bring stronger concurrency (advances in worker_threads, new protocols) and built-in security scanning.

The timeline below shows important milestones in both AI and Node.js:

gantt
  dateFormat  YYYY
  title AI and Node.js Development Timeline
  section AI Developments
    GPT-3 Released         :milestone, 2020,    1d
    ChatGPT Launch         :milestone, 2022,    1d
    GPT-4 Released         :milestone, 2023,    1d
    Hallucination Research :milestone, 2024,    1d
    GPT-5 Anticipated      :milestone, 2025,    1d
  section Node.js Versions
    Node.js 14 LTS         :milestone, 2020,    1d
    Node.js 18 LTS         :milestone, 2022,    1d
    Node.js 20 LTS         :milestone, 2023,    1d
    Node.js 26 (latest)    :milestone, 2026,    1d

The diagram above includes large models such as GPT-3 (2020) and GPT-4 (2023), as well as new research areas (hallucination categories, etc.). Important Node.js LTS versions have also been added. This technology development line points to upcoming changes for both the AI and Node.js communities. For example, the development of GPT-5's logical reasoning and security orientations may indicate that integration with Node.js applications will become safer. Likewise, in future Node.js releases, stream management and process parallelism may be further improved.

References

Matt Watson, AI-proof Node.js Developer Interview Questions, Full Scale (June 2026).
Jens Wessling, "We Asked 100+ AI Models to Write Code. Here's How Many Failed Security Tests." Veracode Blog (July 2025).
SoftwareSeni, Why 45 Percent of AI Generated Code Contains Security Vulnerabilities (November 2025).
Fang Liu et al., "Beyond Functional Correctness: Exploring Hallucinations in LLM-Generated Code", ArXiv (April 2024).
Laurence Santy, 15 Things AI Can — and Can't Do (So Far), Invoca Blog (March 2025).
Veracode 2025 GenAI Code Security Report, Veracode (July 2025).
IBM, What is a context window? (IBM Think).
Node.js Documentation, worker_threads, cluster, stream (v26.5.0).
DEV Community (Atlas Whoff), Node.js Streams: Processing Large Files Without Running Out of Memory (April 2020).
Full Scale Booklet (Matt Watson), Product Driven: Build Something People Want (2023) — Node.js best practices.

Flip duel

DevUnionX — Tue, 23 Jun 2026 15:17:07 +0000

DevUnionX

Jun 23

(New!)5 Things Even AI Can't Do, Fetch API

#api #webdev #programming #productivity

19 min read

(New!)5 Things Even AI Can't Do, Fetch API

DevUnionX — Tue, 23 Jun 2026 15:16:51 +0000

MY GAME PUBLISHED IN PLAY STORE

Flip Duel: Online Card Battle - Apps on Google Play

Outsmart rivals in 1v1 card duels. Joker, bluff, ranked PvP. 5 rounds.

play.google.com

AI is genuinely good at writing the fetch() one-liner. Ask Copilot, Cursor, Claude, or ChatGPT for "fetch some JSON from this endpoint" and you'll get the canonical happy-path snippet back instantly:

fetch('/api/user')
  .then(res => res.json())
  .then(data => console.log(data))
  .catch(err => console.error(err));

It compiles. It runs. It demos beautifully. And it is wrong in almost every way that matters once real traffic hits it.

This is the second piece in a series about where AI coding assistants break down on specific, widely-used pieces of the web platform. The first looked at React Query. The thesis carries over verbatim: large language models don't produce correct code, they produce plausible code. They're trained to predict the most likely next token given everything they've seen in public repos, and public repos are overflowing with the same happy-path fetch().then(res => res.json()) snippet copy-pasted ten million times. So that's the median of what you get back. It looks right. It passes the vibe check. It even passes a quick manual test against a working endpoint. Then it hits a 500, a flaky network, a slow server, a streaming response, or a cross-origin cookie, and the gap between "looks right" and "is right" is exactly where your production incident lives.

The Fetch API is a particularly brutal proving ground for this, because fetch() has a bunch of deliberately surprising, low-level semantics that contradict what developers (and the training data) intuitively expect. It's a primitive, not a batteries-included HTTP client. The things it leaves to you — error semantics, cancellation, streaming, resilience, body lifecycle, CORS, runtime differences — are exactly the things that depend on your API contract, your auth setup, your idempotency guarantees, and your failure modes. None of that context lives in any codebase the model trained on. It cannot reason about it because it has never seen it.

Here are the five things AI consistently gets wrong with fetch(), why it gets them wrong, and what you actually have to own yourself.

1. fetch Doesn't Reject on HTTP Errors — and AI Forgets This Every Time

This is the single most common Fetch bug AI produces, and it produces it constantly.

Here's the mental model nearly every developer (and every model trained on their code) brings to fetch(): "if the request fails, the promise rejects and I'll catch it." That model is wrong, and it comes largely from years of jQuery's $.ajax() and from libraries like Axios, which do reject on 4xx/5xx. fetch() does not.

Straight from MDN: a fetch() promise "only rejects when the request fails, for example, because of a badly-formed request URL or a network error. A fetch() promise does not reject if the server responds with HTTP status codes that indicate errors (404, 504, etc.). Instead, a then() handler must check the Response.ok and/or Response.status properties."

So this AI-generated code:

// ❌ What AI writes — looks like real error handling, isn't
async function getUser(id) {
  try {
    const res = await fetch(`/api/users/${id}`);
    const user = await res.json();   // 404? 500? Doesn't matter, we're here anyway
    return user;
  } catch (err) {
    // This ONLY runs on network failure, DNS failure, CORS block, or abort.
    // A 404 or 500 sails right past it.
    console.error('Request failed:', err);
    throw err;
  }
}

…silently treats a 500 Internal Server Error as success. The try/catch gives a false sense of safety — it looks like robust error handling, and a reviewer skimming the PR sees a try/catch and moves on. But for a 404 or 500, fetch() resolves normally with response.ok === false, and execution proceeds to res.json(). At that point one of two things happens: either the error body happens to be valid JSON and you return an error payload as if it were a user object, or (very commonly) the server returned an HTML error page and res.json() throws a confusing SyntaxError: Unexpected token '<' — which lands in your catch block and gets misreported as a parse error rather than the 500 it actually was.

response.ok is true only for statuses in the 200–299 range. You have to check it yourself:

// ✅ Correct — explicitly check response.ok and separate error classes
async function getUser(id) {
  let res;
  try {
    res = await fetch(`/api/users/${id}`);
  } catch (err) {
    // Genuine transport-level failure: offline, DNS, CORS, aborted.
    throw new NetworkError(`Network request failed: ${err.message}`, { cause: err });
  }

  if (!res.ok) {
    // The server answered — it just answered with an error.
    // Read the body for the API's error detail (often JSON on a 400/422).
    let detail;
    try {
      detail = await res.json();
    } catch {
      detail = await res.text().catch(() => null);
    }
    throw new HttpError(res.status, detail);
  }

  return res.json();
}

Why can't AI just do this? It often can if you explicitly prompt "remember fetch doesn't throw on HTTP errors." But left to its own devices it reaches for the statistically dominant pattern, which is the broken one. More importantly, the interesting decisions here are ones AI can't make for you:

Is a 404 an error or an expected outcome? For GET /api/users/123, a 404 might be a real error. For GET /api/users/by-email?x=... used as an existence check, a 404 is a normal "no" and should resolve to null, not throw. AI has no idea which of these your endpoint is.
Does your API put error details in the body on a 400/422? Most well-designed APIs return field-level validation errors in the response body of a 4xx. Whether you should read that body, and what shape it takes, is part of your API contract.
Should network errors and HTTP errors be handled the same way? Almost never. A network error is often retryable; a 400 never is. Conflating them — which the naive try/catch does — destroys your ability to build sane retry logic later.

That distinction between "transport failed" and "server said no" is a semantic, architectural decision about your system. The model can scaffold the syntax; it cannot make the call.

2. Cancellation, AbortController, and the Race Conditions AI Can't See

The second thing AI reliably botches is request cancellation, because cancellation is invisible in the happy path. The code works fine in a demo. It leaks, races, and throws spurious errors in production.

Native fetch() has no cancellation built into the call itself. You cancel by passing an AbortSignal, and you trigger the abort through an AbortController. AI knows this pattern exists — it's in the training data — but it routinely (a) forgets to wire it up at all, (b) fails to clean it up in React, and (c) mishandles the AbortError that results.

The React useEffect leak

Ask an assistant to "fetch data in a React component" and you'll usually get this:

// ❌ No cancellation, no cleanup — race conditions + state-update-after-unmount
function UserProfile({ userId }) {
  const [user, setUser] = useState(null);

  useEffect(() => {
    fetch(`/api/users/${userId}`)
      .then(res => res.json())
      .then(setUser);
  }, [userId]);

  return <div>{user?.name}</div>;
}

Two bugs hide here. First, if the component unmounts before the request resolves, you call setUser on an unmounted component — a leak and a React warning. Second, and worse, is the race condition: if userId changes quickly (say a user clicks through a list), you fire request A then request B. There is no guarantee they resolve in order. As the React docs themselves note, "network responses may arrive in a different order than you sent them." If A resolves after B, you'll display data for the old userId and it will sit there, stale and wrong, with no error anywhere.

The fix is to abort on cleanup:

// ✅ AbortController in cleanup cancels the stale request
function UserProfile({ userId }) {
  const [user, setUser] = useState(null);
  const [error, setError] = useState(null);

  useEffect(() => {
    const controller = new AbortController();

    async function load() {
      try {
        const res = await fetch(`/api/users/${userId}`, {
          signal: controller.signal,
        });
        if (!res.ok) throw new HttpError(res.status);
        setUser(await res.json());
      } catch (err) {
        // The abort is EXPECTED. It is not an error to surface to the user.
        if (err.name === 'AbortError') return;
        setError(err);
      }
    }

    load();
    return () => controller.abort();   // cancel on unmount or when userId changes
  }, [userId]);

  if (error) return <div>Something went wrong.</div>;
  return <div>{user?.name}</div>;
}

The subtle part that AI almost always misses is the if (err.name === 'AbortError') return; line. When you call controller.abort(), the in-flight fetch() rejects with a DOMException named AbortError. If your catch block doesn't special-case it, you'll catch your own intentional cancellation and render an error state — the dreaded flash of "Something went wrong" every time the user navigates. The naive code doesn't even have the abort, so it never learns this lesson; the slightly-less-naive code adds the abort but forgets to filter the error. Both are common AI outputs.

Note also that an abort can fire after the response headers arrive but before the body is read. Per MDN, if you abort after fetch() has fulfilled but before you've read the body, "attempting to read the response body will reject with an AbortError exception." So the guard has to wrap the .json() call too, not just the fetch().

Timeouts and combining signals

Native fetch() has no timeout. None. A request can hang indefinitely. AI, asked for a timeout, will usually produce the old setTimeout(() => controller.abort(), 5000) dance — which works, but is verbose and leaks the timer if the request succeeds first. The modern primitives are cleaner, and AI underuses them because they're newer than the bulk of its training data:

// ✅ AbortSignal.timeout() — declarative per-request timeout
const res = await fetch(url, { signal: AbortSignal.timeout(5000) });

// ✅ AbortSignal.any() — combine a user-cancel signal with a timeout
const userCancel = new AbortController();
const res2 = await fetch(url, {
  signal: AbortSignal.any([userCancel.signal, AbortSignal.timeout(5000)]),
});

AbortSignal.timeout(ms) returns a signal that aborts on its own after the given time, and — importantly — per MDN it "rejects with a TimeoutError DOMException," distinct from the AbortError you get from a manual controller.abort(). That distinction lets you tell "the server was too slow" apart from "the user navigated away," which matters for whether you show a message and whether you retry. AbortSignal.any([...]) composes multiple signals into one that fires on the first abort — though MDN notes that, unlike timeout(), with any() "there is no way to tell whether the final abort was caused by a timeout." Both are Baseline across modern browsers since 2024 (for any(): Chrome 116+, Firefox 124+, Safari 17+); both are available in Node 18+/20+. If you support older targets, feature-detect or polyfill.

One honest caveat the model will never volunteer: there's a long-standing Chromium quirk where a fetch aborted by AbortSignal.timeout() sometimes surfaces as AbortError rather than TimeoutError. If you branch on the error name, test it in the browsers you actually ship to.

And the deepest point: client-side abort only stops the client. It frees the connection and stops you waiting. If the server already received the request, it may keep right on processing — charging the card, sending the email. For read-only requests that's fine. For mutations it's not, and the answer is server-side idempotency, which is squarely your design problem, not something fetch() or an AI can paper over.

3. Streaming the Response Body — Where AI Falls Apart Completely

The third area is streaming, and it's where AI's limitations are starkest, because correct streaming code requires reasoning about byte boundaries, buffering, and protocol framing — things that are genuinely hard to pattern-match.

By default, AI treats every response as a monolith: await res.json() or await res.text(), get the whole thing, done. That's correct for a 2KB JSON payload. It's a disaster for a streaming LLM response, a large NDJSON export, or a Server-Sent Events feed, where the entire point is to process bytes as they arrive. response.body is a ReadableStream of Uint8Array chunks, and consuming it correctly is fiddly.

Here's the kind of streaming loop AI tends to write when you push it toward streaming:

// ❌ Subtly broken in (at least) two ways
async function streamTokens(url, onToken) {
  const res = await fetch(url);
  const reader = res.body.getReader();

  while (true) {
    const { value, done } = await reader.read();
    if (done) break;

    const text = new TextDecoder().decode(value);   // BUG 1
    for (const line of text.split('\n')) {            // BUG 2
      if (line.startsWith('data: ')) {
        onToken(JSON.parse(line.slice(6)));
      }
    }
  }
}

There are two classic, production-breaking bugs here, and AI produces both because the broken version appears all over the internet:

Bug 1 — multi-byte characters split across chunks. Network chunks are arbitrary byte boundaries. A multi-byte UTF-8 character (an emoji, a CJK glyph, an accented letter) can be split across two read() calls. Calling new TextDecoder().decode(value) on each chunk independently corrupts any character straddling the boundary, replacing it with the � replacement character. The fix is to reuse a single decoder with streaming mode: decoder.decode(value, { stream: true }), which buffers the incomplete trailing bytes until the rest arrives. Or pipe through a TextDecoderStream, which handles this for you.

Bug 2 — delimiters split across chunks. A chunk can end in the middle of a line. text.split('\n') on a single chunk will mangle any record that spans a boundary — you'll get half a JSON object and a JSON.parse throw. You must keep a buffer across reads and only process complete lines, retaining the trailing partial fragment for the next iteration.

Here's a version that actually survives the network:

// ✅ Correct: single streaming decoder + cross-chunk line buffer
async function streamSSE(url, onMessage, signal) {
  const res = await fetch(url, { signal });
  if (!res.ok) throw new HttpError(res.status);

  // pipeThrough(TextDecoderStream()) handles multi-byte boundaries for us.
  const reader = res.body
    .pipeThrough(new TextDecoderStream())
    .getReader();

  let buffer = '';
  try {
    while (true) {
      const { value, done } = await reader.read();
      if (done) break;

      buffer += value;
      const lines = buffer.split('\n');
      buffer = lines.pop() ?? '';   // keep the last, possibly-incomplete line

      for (const line of lines) {
        if (!line.startsWith('data: ')) continue;
        const data = line.slice(6);
        if (data === '[DONE]') return;
        try {
          onMessage(JSON.parse(data));
        } catch {
          /* ignore keep-alive / partial frames */
        }
      }
    }
    // flush any trailing complete record left in the buffer
    if (buffer.startsWith('data: ')) {
      onMessage(JSON.parse(buffer.slice(6)));
    }
  } finally {
    reader.releaseLock();
  }
}

A few things worth noting that AI rarely gets right on its own:

for await (const chunk of response.body) async iteration is not universally supported. It reads cleaner, but Safari didn't support it for a while, so the explicit getReader() loop remains the production-safe choice. AI will happily suggest the async-iterator form without flagging the support gap.
For real SSE in the browser, EventSource already handles all of this — parsing, reconnection, the \n\n framing — but it's GET-only and can't send custom headers (no Authorization). The reason people hand-roll SSE over fetch is precisely to POST a body and set auth headers. That trade-off is a judgment call about your API; AI doesn't know you need a bearer token, so it can't tell you which approach fits.
Backpressure. A reader naturally applies backpressure — you don't pull the next chunk until you've processed the current one — but if you spin the loop and buffer everything into memory regardless, you've thrown that away. Whether that matters depends on payload size and your environment, which, again, is context the model lacks.

Correct streaming is a reasoning problem about byte framing and protocol, not a recall problem. That's why AI does so badly at it.

4. Retries, Timeouts, and Resilience — Logic AI Can't Architect for Your API

Native fetch() has no retry logic, no backoff, no timeout. Resilience is entirely yours to build, and this is the category where AI's output is the most dangerous, because a naive retry loop doesn't just fail to help — it can actively make an outage worse.

Here's the retry loop AI loves to write:

// ❌ Dangerous: retries everything, no backoff, retries non-idempotent writes
async function fetchWithRetry(url, options, retries = 3) {
  for (let i = 0; i < retries; i++) {
    try {
      const res = await fetch(url, options);
      if (res.ok) return res;
    } catch (err) {
      // swallow and try again
    }
  }
  throw new Error('Failed after retries');
}

Count the ways this hurts you in production:

It retries non-idempotent requests. If options.method is POST and the request actually reached the server and succeeded — but the response got lost — this retries it and you double-charge the customer or create two orders. AWS's own resilience guidance (Marc Brooker, Timeouts, retries and backoff with jitter, Amazon Builders' Library) is blunt: "In general, our view is that APIs with side effects aren't safe to retry unless they provide idempotency. This guarantees that the side effects happen only once no matter how often you retry."
It retries 4xx. A 400, 401, 403, or 422 will never succeed on retry — the request is malformed or unauthorized. The AWS Well-Architected Framework (REL05-BP03) explicitly warns against "retrying all errors, including those with a clear cause that indicates lack of permission, configuration error, or another condition that predictably will not resolve without manual intervention." You should only retry genuinely transient failures: network errors, 429, and 503 (often 502/504).
It has no backoff. Immediate retries are a stampede. When a service is already struggling, a fleet of clients retrying in a tight loop is precisely how a brief blip becomes a cascading failure.
It ignores Retry-After. A 429 or 503 frequently comes with a Retry-After header telling you exactly how long to wait. The naive loop steamrolls it.
No jitter. Even with exponential backoff, if every client backs off on the same schedule they retry in synchronized waves — the "thundering herd." Randomized jitter spreads them out.

A defensible version encodes real decisions:

// ✅ Retries only what's safe, with backoff + jitter + Retry-After
const RETRYABLE_STATUS = new Set([429, 502, 503, 504]);

async function resilientFetch(url, {
  method = 'GET',
  maxRetries = 3,
  baseDelay = 300,
  ...options
} = {}) {
  // Only retry idempotent methods unless the caller explicitly opts in.
  const idempotent = ['GET', 'HEAD', 'PUT', 'DELETE'].includes(method);

  for (let attempt = 0; ; attempt++) {
    let res;
    try {
      res = await fetch(url, {
        method,
        signal: AbortSignal.timeout(10_000),
        ...options,
      });
    } catch (err) {
      // network error or timeout — retryable if idempotent and budget remains
      if (!idempotent || attempt >= maxRetries) throw err;
      await sleep(backoff(attempt, baseDelay));
      continue;
    }

    if (res.ok) return res;
    if (!RETRYABLE_STATUS.has(res.status) || !idempotent || attempt >= maxRetries) {
      throw new HttpError(res.status, await res.text().catch(() => null));
    }

    // Respect Retry-After (seconds or HTTP-date) when present.
    const retryAfter = parseRetryAfter(res.headers.get('Retry-After'));
    await sleep(retryAfter ?? backoff(attempt, baseDelay));
  }
}

function backoff(attempt, base) {
  const exp = base * 2 ** attempt;          // 300, 600, 1200, ...
  return exp + Math.random() * base;        // full-ish jitter
}
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

But here's the real point: even this is just a template. The genuinely important questions are ones only you can answer, because they depend on your system:

Which of your endpoints are actually idempotent? A POST /search is safe to retry. A POST /charge is not — unless you send an idempotency key, which is a server-side contract you have to design and the server has to honor. AI cannot inspect your backend to know which is which.
What's your retry budget across layers? If your client retries 3×, your API gateway retries 3×, and your service-to-service calls retry 3×, you've just built a 27× load amplifier for a single user action. Coordinating retry budgets across the stack is an architecture problem.
Should you even retry, or fail fast? Sometimes the right answer for an interactive request is to surface the error immediately and let the user decide, not to make them wait through three silent backoffs.

These are decisions about your failure modes and your tolerance for duplication and latency. The model has no model of your system. It pattern-matches a retry loop from GitHub and hands it to you with the unsafe defaults baked in.

5. The Subtle Semantics: Body Lifecycle, CORS, Content-Type, Redirects, and Node vs Browser

The last category is a grab-bag of low-level fetch() semantics that are individually small but collectively responsible for a huge share of "why is this broken" debugging sessions. AI gets these wrong because they're the kind of detail that's underrepresented in training data relative to the happy path.

The body can only be read once

A response body is a stream. Once you consume it — .json(), .text(), .arrayBuffer(), .formData(), .blob() — it's gone. Call a second consuming method and you get TypeError: Body has already been consumed (or body stream already read).

// ❌ Throws on the second read
const res = await fetch(url);
const data = await res.json();
const raw = await res.text();   // 💥 "Body has already been consumed"

// A subtler version of the same bug — logging the body, then returning it:
async function loggingFetch(url) {
  const res = await fetch(url);
  console.log(await res.text());   // consumes the body...
  return res.json();               // 💥 ...so this throws
}

This bites hard in middleware, interceptors, and caching layers — anywhere one piece of code wants to peek at the body and another wants to use it. The fix is response.clone() before the first read:

// ✅ Clone before reading if you need the body twice
async function loggingFetch(url) {
  const res = await fetch(url);
  const audit = res.clone();        // clone first
  console.log(await audit.text());  // read the clone
  return res.json();                // original still intact
}

Per MDN, clone() "throws a TypeError if the response body has already been used" — so the clone must happen first. And a performance caveat the model won't mention: if you read the two branches at very different speeds, the faster one forces the slower one's data to buffer in memory, so clone() is fine for read-twice-in-sequence but not for tee-ing a huge body to two slow consumers. The same one-shot rule applies to request bodies, which is why you can't fetch(request) the same Request object twice without cloning it.

CORS and credentials — AI cannot reason about your origin setup

fetch() defaults to mode: 'cors' and, critically, credentials: 'same-origin'. That means by default, cookies are not sent on cross-origin requests. Developers (and AI) are constantly surprised that their authenticated cross-origin call returns a 401, because the session cookie silently wasn't attached.

// ❌ Cross-origin call that needs the session cookie — but doesn't send it
await fetch('https://api.example.com/me');   // credentials default to same-origin

// ✅ Explicitly include credentials for cross-origin auth
await fetch('https://api.example.com/me', { credentials: 'include' });

But credentials: 'include' is necessary, not sufficient. For a credentialed cross-origin request to actually work, the server must respond with Access-Control-Allow-Credentials: true and an explicit Access-Control-Allow-Origin echoing your exact origin — the * wildcard is forbidden with credentials. And a SameSite=Strict/Lax cookie won't be sent cross-site regardless of what you put in fetch. This is the perfect example of something AI structurally cannot do: it doesn't know whether your API is same-origin or cross-origin, whether it's cookie-based or bearer-token-based, how your SameSite attributes are set, or what your server's CORS config looks like. None of that is in the code it's editing. It guesses, and it's frequently wrong, and the failure shows up as an opaque CORS console error that gives JavaScript no detail by design.

Content-Type: when fetch sets it, and when you must

For a JSON body you must set the header yourself; the model usually gets this one right:

// ✅ JSON — you set Content-Type
await fetch('/api/items', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ name: 'Widget' }),
});

But the inverse is the trap. When you pass a FormData body, the browser sets Content-Type: multipart/form-data for you, including the all-important boundary parameter. If you "helpfully" set it yourself — which AI does constantly, applying the JSON pattern by analogy — you omit the boundary and the server can't parse the body:

// ❌ Setting Content-Type manually with FormData breaks the boundary
await fetch('/upload', {
  method: 'POST',
  headers: { 'Content-Type': 'multipart/form-data' },   // 🔴 no boundary → server fails
  body: formData,
});

// ✅ Let the browser set it — including the boundary
await fetch('/upload', { method: 'POST', body: formData });

Same goes for URLSearchParams bodies, which auto-set application/x-www-form-urlencoded; charset=UTF-8. The rule — "set it for JSON, never set it for FormData/URLSearchParams" — is exactly the kind of conditional, counterintuitive detail AI flattens into "always set Content-Type."

Redirects

By default fetch() follows redirects transparently (redirect: 'follow'), and response.url gives you the final URL while response.redirected tells you whether a redirect happened. If you need to prevent redirects for security reasons, MDN is explicit that checking response.redirected after the fact is unsafe — "by the time a response is received, the redirect has already happened, and you may have sent the request to an unintended destination, potentially sending sensitive information." The correct approach is redirect: 'error' (or 'manual') set on the request up front. This is a security nuance AI won't surface unless you know to ask.

Browser vs Node — same API, different behavior

fetch() has been global in Node since v18 (via undici) and stable since Node v21 — as LogRocket puts it, fetch "was added to the Node.js core in v18. However, until v21, it was mostly experimental... The stable release in v21 is a big milestone." It's exposed with no import, and it looks identical to the browser. It is not identical, and the differences are precisely the kind of environment-specific behavior AI conflates:

Node applies default timeouts the browser doesn't. Per the nodejs/undici docs (Client API), undici sets bodyTimeout and headersTimeout to 300e3 — "Defaults to 300 seconds" each (older undici 5.x bundled in early Node 18 used 30e3/30s), and you'll see errors with code UND_ERR_HEADERS_TIMEOUT. There is no equivalent default in the browser — there, an un-aborted request can hang forever.
Node does not enforce CORS. Verbatim from the undici docs: "Unlike browsers, Undici does not implement CORS (Cross-Origin Resource Sharing) checks by default... No preflight requests are automatically sent for cross-origin requests. No validation of Access-Control-Allow-Origin headers is performed. Requests to any origin are allowed regardless of the source." All the CORS reasoning above simply doesn't apply server-side — which means code that "works" in your Node tests can still fail in the browser.
You must consume or cancel the body in Node, or leak connections. The undici docs warn that "Garbage collection in Node is less aggressive and deterministic... which means that leaving the release of connection resources to the garbage collector can lead to excessive connection usage, reduced performance... and even stalls or deadlocks when running out of connections. Therefore, it is important to always either consume or cancel the response body." In the browser, GC bails you out. In Node it doesn't.
There's no browser cookie jar, no SameSite, no origin server-side, and undici exposes non-standard extensions (a dispatcher option for proxies/pooling, async-iterable request bodies requiring duplex: 'half') that don't exist in browsers at all.

AI trained on a mix of browser and Node code will cheerfully mix their assumptions. It can't tell which runtime your file targets, so it can't warn you when a browser assumption will break in Node or vice versa.

How to Actually Use AI With fetch

None of this is an argument against using AI assistants. They're a genuine accelerator. It's an argument for knowing exactly where the line is.

Here's the division of labor that works:

Let AI do the scaffolding. The boilerplate fetch() call, the shape of an async function, the wiring of an AbortController, the skeleton of a retry loop, the JSON-body POST — let it type all of that. It's fast and it's usually structurally fine. This is "acceleration mode": you know what you want, AI gets you there faster.

You own the semantics. Specifically:

Error handling — because whether a 404 is an error, whether the error body matters, and how network failures differ from HTTP failures depends on your API contract. Always check response.ok; never let a try/catch lull you into thinking a 500 was handled.
Cancellation — because cleanup, race conditions, and abort-error filtering depend on your component lifecycle and UX. Wire an AbortController into every effect; filter AbortError.
Streaming — because correct byte buffering and protocol framing is a reasoning problem AI fails at, and the EventSource-vs-fetch trade-off depends on your auth needs. Use a single streaming decoder and a cross-chunk buffer.
Resilience — because what to retry, when, and how hard depends entirely on your idempotency guarantees and failure modes, and the unsafe defaults AI ships can amplify an outage. Retry only idempotent, transient failures; back off with jitter; honor Retry-After.
The semantics — body lifecycle (clone() before reading twice), CORS/credentials, Content-Type rules, redirects, and runtime differences, because these are counterintuitive details AI flattens and your environment determines.

A practical workflow: generate the call, then run a checklist against it — Does it check response.ok? Is there a signal wired in and an abort path? If it streams, does it buffer across chunks? If it retries, what exactly does it retry and is that method idempotent? Are credentials/Content-Type correct for this origin and body type? Does this run in Node, the browser, or both? That checklist is the part of the job that doesn't transfer to the model.

The unifying theme, the same one from the React Query piece: AI optimizes for code that looks plausible and probably compiles, not for code with correct semantics on the actual web platform. The Fetch API is a low-level primitive that deliberately hands you the hard decisions — and those decisions require context about your specific API, auth setup, idempotency, and failure modes that simply does not exist in any codebase the model was trained on. That's not a limitation that a better model fixes. It's a category of work that is, definitionally, yours.

Use AI to write the fetch. Reason about everything that happens after it resolves yourself.

(Alert!)5 Things Even AI Can't Do, React Query

DevUnionX — Sat, 20 Jun 2026 09:37:01 +0000

GraphQL: A Complete Guide for Developers in 2026

MY GAMES JUST LAUNCHED

Flip Duel: Online Card Battle - Apps on Google Play

Outsmart rivals in 1v1 card duels. Joker, bluff, ranked PvP. 5 rounds.

play.google.com

If you have built more than a couple of APIs, you have probably felt the friction of REST at scale. You ship an endpoint, the frontend team asks for one more field, you version the route, the mobile team needs a different shape of the same data, and six months later you are maintaining /v3/users/:id/full next to /v2/users/:id/summary and nobody remembers which one the Android app actually calls.

GraphQL was built to kill that exact pain. It is a query language and runtime that lets clients ask for precisely the data they need — no more, no less — from a single endpoint, against a strongly typed schema that doubles as living documentation.

This guide walks through GraphQL from first principles to production concerns. It is aimed at working developers, so expect schema definitions, resolvers, real queries, the N+1 problem, federation, security, and the parts of the ecosystem that actually matter in 2026. By the end you should be able to decide whether GraphQL belongs in your stack and how to build it without shooting yourself in the foot.

What GraphQL Actually Is

GraphQL is a specification, not a library or a framework. It was created at Facebook in 2012 to power their mobile apps, open-sourced in 2015, and is now governed by the GraphQL Foundation under the Linux Foundation. The spec defines a query language, a type system, and an execution model — but it deliberately says nothing about which database you use, which programming language you implement it in, or how you transport requests over the wire.

That last point trips people up, so let it sink in: GraphQL is transport-agnostic and storage-agnostic. Most implementations run over HTTP with JSON, but that is a convention, not a requirement. Your resolvers can pull data from PostgreSQL, a REST microservice, a gRPC backend, Redis, a flat file, or three of those at once. GraphQL sits as a thin coordination layer in front of whatever you already have.

The mental model is simple. You describe your data as a graph of types. Clients write queries that traverse that graph. The server resolves each requested field by running a function. The response mirrors the shape of the query exactly.

Here is the canonical hello-world. A query:

query {
  user(id: "4") {
    name
    email
    posts(last: 3) {
      title
    }
  }
}

And the response:

{
  "data": {
    "user": {
      "name": "Mary Watson",
      "email": "mary@example.com",
      "posts": [
        { "title": "On the Nature of APIs" },
        { "title": "Why I Stopped Versioning" },
        { "title": "Cursors, Not Offsets" }
      ]
    }
  }
}

Notice three things. The response shape matches the query shape one-to-one. You got exactly the fields you asked for and nothing else. And you fetched a user and their posts in a single round trip, even though those are almost certainly two different tables or services on the backend.

The Problems GraphQL Solves

To appreciate GraphQL you have to be honest about where REST hurts. REST is excellent, widely understood, cache-friendly, and probably the right default for most public APIs. But it has three structural weaknesses that GraphQL attacks directly.

Over-fetching. A REST endpoint returns a fixed payload. GET /users/4 might return forty fields when your screen needs two. On a desktop with fiber this is invisible. On a phone with spotty 4G, those extra kilobytes per request, multiplied across a list view, add up to real latency and battery drain. GraphQL clients request only the fields they render.

Under-fetching and the N+1 round trip. The mirror image. To render a user profile with their recent posts and the comment count on each post, REST often forces you into a waterfall: fetch the user, then fetch their posts, then loop over posts fetching comments. Each step waits for the previous one. The frontend becomes a choreography of chained fetch calls. GraphQL collapses that into one request because the client describes the entire tree it wants up front.

Endpoint proliferation and versioning. REST tends to grow an endpoint per view. A new screen needs a slightly different shape, so you add a route, or a ?include= parameter, or a ?fields= filter, and slowly reinvent a query language badly. GraphQL gives clients that flexibility natively. Because clients select fields explicitly, you can add new fields to a type without ever breaking existing clients — they simply do not ask for the new field. Most GraphQL APIs never version at all; they evolve additively and deprecate fields with metadata rather than spinning up /v2.

The flip side, which we will cover, is that GraphQL trades these wins for harder caching, a more involved server setup, and new categories of performance and security concern. There is no free lunch.

The Type System and Schema Definition Language

Everything in GraphQL starts with the schema. The schema is a contract written in the Schema Definition Language (SDL) that declares every type, every field, and every operation your API supports. It is strongly typed and introspectable, which is what powers autocomplete in tooling, codegen, and validation before a single resolver runs.

Let's build out a small blog API to make the type system concrete.

type User {
  id: ID!
  name: String!
  email: String
  role: Role!
  posts: [Post!]!
}

type Post {
  id: ID!
  title: String!
  body: String!
  published: Boolean!
  author: User!
  comments: [Comment!]!
}

type Comment {
  id: ID!
  text: String!
  author: User!
}

enum Role {
  ADMIN
  EDITOR
  READER
}

A few things to unpack here, because the syntax is dense with meaning.

Scalars are the leaf values. GraphQL ships with five built-in scalars: Int, Float, String, Boolean, and ID. ID is a string under the hood but signals "this is a unique identifier" to tooling. You can and should define custom scalars like DateTime, Email, or URL to add validation and semantic meaning.

The exclamation mark means non-null. String! is a string that will never be null. [Post!]! is a non-null list of non-null posts — the list itself is always present (possibly empty), and no element inside it is ever null. [Post] would be a nullable list that may contain nulls. This nullability system is one of GraphQL's quietest strengths: it pushes a huge class of "cannot read property of undefined" bugs into the type checker.

Object types like User and Post are the nodes of your graph, and the fields that point to other object types are the edges. User.posts connects a user to its posts; Post.author connects back. That bidirectional linking is exactly why it is called a graph.

Beyond objects and scalars, the type system has a few more tools you will reach for constantly.

Enums restrict a field to a fixed set of values, as Role shows above. Input types describe the structured arguments you pass into mutations — they look like object types but use the input keyword and cannot have fields that resolve to object types. Interfaces define a set of fields that multiple types must implement. Unions say a field can return one of several types that need not share any fields.

Here is an interface and a union in practice:

interface Node {
  id: ID!
}

type Image implements Node {
  id: ID!
  url: String!
  altText: String
}

type Video implements Node {
  id: ID!
  url: String!
  durationSeconds: Int!
}

union SearchResult = User | Post | Image

input CreatePostInput {
  title: String!
  body: String!
  published: Boolean = false
}

The Node interface is the foundation of the Relay specification for global object identification — any type implementing Node can be refetched by its global id. Unions are perfect for search results or activity feeds where heterogeneous types share a list. Note the default value published: Boolean = false in the input — defaults are first-class in SDL.

Finally, the three special root operation types are the entry points into the entire graph:

type Query {
  user(id: ID!): User
  posts(published: Boolean): [Post!]!
  search(term: String!): [SearchResult!]!
}

type Mutation {
  createPost(input: CreatePostInput!): Post!
  deletePost(id: ID!): Boolean!
}

type Subscription {
  postPublished: Post!
}

Query is for reads, Mutation is for writes, and Subscription is for real-time streams. Every operation a client can perform must be reachable from one of these three roots. This is the complete public surface of your API in one readable document — which is precisely why a good schema is the single most important artifact in a GraphQL project.

Queries: Asking for Data

A query selects fields starting from the Query root and walking down the graph. The shape you write is the shape you get back.

query GetDashboard {
  posts(published: true) {
    id
    title
    author {
      name
    }
    comments {
      text
    }
  }
}

Arguments like published: true can appear on any field, not just the root. You could ask for comments(last: 5) deep inside the tree, and each field's resolver receives its own arguments. This is far more powerful than REST query parameters, which only apply to the endpoint as a whole.

For anything beyond a hardcoded example you want variables rather than string interpolation. Variables keep your query static (which matters for caching and persisted queries) and let the client pass values separately:

query GetUser($id: ID!, $postCount: Int = 10) {
  user(id: $id) {
    name
    posts(last: $postCount) {
      title
    }
  }
}

{ "id": "4", "postCount": 3 }

Variables are declared in the operation signature with their types and optional defaults, then referenced with $. Never build queries with string concatenation — it is the GraphQL equivalent of SQL injection waiting to happen, and it defeats caching.

Aliases let you request the same field twice with different arguments, which would otherwise collide in the response object:

query {
  recent: posts(last: 5) { title }
  popular: posts(orderBy: VIEWS, last: 5) { title }
}

Fragments are reusable selection sets. They keep queries DRY and, more importantly, are the mechanism that powers component-colocated data requirements in modern clients:

fragment PostCard on Post {
  id
  title
  author { name }
}

query {
  posts(published: true) {
    ...PostCard
  }
}

At GraphQLConf 2025, fragments were a recurring theme, with the community converging on the idea that fragments are primarily for describing a UI component's data dependencies, not just for reuse. A <PostCard /> React component declares exactly the data it needs as a fragment, and the page query composes those fragments. This pattern, long used internally at Meta with Relay, has now spread across Apollo, urql, and the GraphQL Code Generator client preset.

Directives modify execution. The two built into the spec are @include and @skip, which conditionally add or remove fields:

query GetUser($id: ID!, $withPosts: Boolean!) {
  user(id: $id) {
    name
    posts @include(if: $withPosts) {
      title
    }
  }
}

There are also incremental-delivery directives like @defer and @stream for streaming parts of a response as they become available — useful when one field is slow and you do not want it to block the rest. Worth noting: at the 2025 conference, Meta unveiled an @async directive precisely because @defer carries hidden overhead, so the streaming story is still actively evolving.

Mutations: Changing Data

Mutations look like queries but live under the Mutation root and signal intent to write. Critically, top-level mutation fields execute serially, one after another, while query fields may run in parallel. This guarantees that if you fire two mutations in one request, the first finishes before the second begins.

mutation PublishPost($input: CreatePostInput!) {
  createPost(input: $input) {
    id
    title
    published
  }
}

A mutation returns data just like a query — and you should lean into that. Return the modified object (and anything else that changed) so the client can update its cache without a refetch. A common best practice is to return a dedicated payload type that wraps the result alongside metadata and typed errors:

type CreatePostPayload {
  post: Post
  errors: [UserError!]!
}

type UserError {
  field: String
  message: String!
}

This pattern — modeling expected errors (validation failures, business-rule violations) as part of the schema rather than throwing them into the top-level errors array — was explicitly endorsed at GraphQLConf 2025 as the way to design scalable, future-proof APIs. It separates "the user typed an invalid email" (a normal, typed outcome) from "the database is on fire" (a real exception).

Subscriptions: Real-Time Data

Subscriptions push data to the client when an event occurs, rather than the client polling. They are the basis for live chat, notifications, collaborative editing, and dashboards.

subscription OnPostPublished {
  postPublished {
    id
    title
    author { name }
  }
}

Under the hood subscriptions usually run over WebSockets (via the graphql-ws protocol) or Server-Sent Events. The server holds the connection open and emits a payload each time the underlying event fires. Be aware that subscriptions are the hardest part of GraphQL to operate at scale — they hold long-lived connections, complicate horizontal scaling, and historically have been painful in federated setups. Recent work like event-driven federated subscriptions (EDFS) and various SSE-to-WebSocket gateway bridges is actively closing those gaps, but for many teams a simpler polling or @defer approach is the pragmatic starting point.

Resolvers: Where the Work Happens

The schema describes what is possible. Resolvers are the functions that actually produce the data for each field. This is where GraphQL meets your real backend.

A resolver is a function that receives four arguments, conventionally (parent, args, context, info):

parent — the result of the parent field's resolver (also called root or source).
args — the arguments supplied to this field in the query.
context — a per-request object shared across all resolvers, ideal for the authenticated user, database connections, and loaders.
info — metadata about the execution state, including the requested fields. Rarely needed but powerful.

Here is a minimal server using Apollo Server, the most popular Node.js implementation, wired to the blog schema:

import { ApolloServer } from "@apollo/server";
import { startStandaloneServer } from "@apollo/server/standalone";

const typeDefs = `#graphql
  type User {
    id: ID!
    name: String!
    posts: [Post!]!
  }
  type Post {
    id: ID!
    title: String!
    author: User!
  }
  type Query {
    user(id: ID!): User
    posts: [Post!]!
  }
`;

const resolvers = {
  Query: {
    user: (parent, args, context) => context.db.getUser(args.id),
    posts: (parent, args, context) => context.db.getPosts(),
  },
  User: {
    posts: (parent, args, context) => context.db.getPostsByAuthor(parent.id),
  },
  Post: {
    author: (parent, args, context) => context.db.getUser(parent.authorId),
  },
};

const server = new ApolloServer({ typeDefs, resolvers });

const { url } = await startStandaloneServer(server, {
  context: async ({ req }) => ({
    db: database,
    user: await authenticate(req.headers.authorization),
  }),
  listen: { port: 4000 },
});

console.log(`Server ready at ${url}`);

The key insight: resolvers are nested and lazy. When a query asks for user.posts.author, GraphQL first runs Query.user, passes that result as parent into User.posts, then for each post passes it as parent into Post.author. Fields you do not request never run their resolvers. You did not write a single JOIN — the execution engine walked the graph for you.

If a field's value can simply be read off the parent object (like User.name from a row that already has a name column), you do not even need to write a resolver. GraphQL provides a default resolver that returns parent[fieldName]. You only write explicit resolvers for fields that require computation, a database hit, or a call to another service.

The Request Lifecycle

Understanding what the server does with an incoming operation demystifies a lot of behavior and performance characteristics. Every request goes through three phases.

Parsing. The raw query string is tokenized and turned into an Abstract Syntax Tree (AST). Syntax errors are caught here before anything else runs.

Validation. The AST is checked against the schema. Does that field exist on that type? Are the argument types correct? Is a non-null variable actually provided? Are fragments used on compatible types? Because the schema is strongly typed, an enormous class of errors is rejected here — before a single resolver or database query executes. This is a major reliability advantage over REST, where a malformed request often only fails deep inside business logic.

Execution. The validated AST is walked, resolvers fire in dependency order, and results are assembled into a response that mirrors the query shape. Query fields can resolve in parallel; mutation fields at the top level run in series.

This pipeline is also where you hook in cross-cutting concerns. Validation rules can reject queries that are too deep or too expensive (more on this under security). The September 2025 spec edition also clarified execution and deprecation semantics, making rolling schema changes more predictable in production.

The N+1 Problem and DataLoader

Now the most important performance pitfall in GraphQL, the one that bites every team eventually.

Recall the nested resolver model. Consider this query:

query {
  posts {       # 1 query: fetch 50 posts
    title
    author {    # runs once PER post: 50 more queries!
      name
    }
  }
}

The posts resolver runs once and returns fifty posts. Then GraphQL runs the Post.author resolver once for each of those fifty posts. If each invocation does SELECT * FROM users WHERE id = ?, you have just fired 51 database queries to render one list. This is the N+1 problem, and naive GraphQL servers are exceptionally prone to it because the nested resolver model makes it so easy to write.

The standard solution is batching and caching per request, implemented by the DataLoader library (originally from Facebook). A DataLoader collects all the individual .load(id) calls that happen within a single tick of the event loop, then dispatches them as one batched request:

import DataLoader from "dataloader";

function createUserLoader(db) {
  return new DataLoader(async (userIds) => {
    // userIds = ['1', '7', '7', '12', ...] collected across all 50 author resolvers
    const users = await db.getUsersByIds(userIds);
    const byId = new Map(users.map((u) => [u.id, u]));
    // must return results in the SAME ORDER as the input keys
    return userIds.map((id) => byId.get(id));
  });
}

// create a fresh loader per request, in context
const server = new ApolloServer({ typeDefs, resolvers });
startStandaloneServer(server, {
  context: async () => ({
    userLoader: createUserLoader(database),
  }),
});

// resolver now uses the loader
const resolvers = {
  Post: {
    author: (post, args, context) => context.userLoader.load(post.authorId),
  },
};

Now those fifty author resolvers each call userLoader.load(authorId), DataLoader batches them into a single WHERE id IN (...) query, and the per-request cache means duplicate IDs are deduplicated for free. Fifty-one queries become two.

Two rules to remember: create a new DataLoader for every request (the cache must not leak between users), and the batch function must return results in exactly the same order as the input keys. Getting the ordering wrong silently mismatches data across records, which is a nasty bug to track down.

GraphQL vs REST: An Honest Comparison

Neither wins universally. Here is how they actually stack up.

GraphQL's advantages. Clients fetch exactly what they need in one round trip, eliminating over- and under-fetching. The strongly typed, introspectable schema gives you free interactive documentation, autocomplete, and end-to-end type safety via codegen. The API evolves additively, so you rarely version. A single endpoint can aggregate many backend services, making it a natural fit for a backend-for-frontend layer.

GraphQL's costs. HTTP caching is harder — since everything is usually a POST to one URL, you lose the free CDN and browser caching that REST's distinct GET URLs give you, and you push caching into the client and application layers instead. The server is more complex to build correctly (resolvers, DataLoader, depth limiting). File uploads and binary data are awkward. And the flexibility that delights clients also opens the door to expensive or malicious queries, so you must add query-cost protections that REST gets somewhat for free.

When REST is the better call. Simple CRUD APIs with stable, predictable shapes. Public APIs where aggressive HTTP/CDN caching is critical. Heavy file transfer. Teams who value the operational simplicity and universal tooling of plain HTTP. There is zero shame in REST; for a huge share of services it remains the right default.

When GraphQL shines. Mobile and SPA frontends with diverse, rapidly changing data needs. Aggregating multiple microservices or third-party APIs behind one graph. Products where many client teams consume one backend and you want them to move independently. Anywhere the cost of round trips and over-fetching is high.

Many mature organizations run both: REST for simple service-to-service and public endpoints, GraphQL as the client-facing aggregation layer. It is not a religious war.

Pagination Done Right

Offset pagination (?page=2&limit=20) is simple but breaks under concurrent writes — insert a row while a user paginates and items shift or duplicate across pages. The GraphQL community has largely standardized on cursor-based pagination via the Relay Connections specification.

type PostConnection {
  edges: [PostEdge!]!
  pageInfo: PageInfo!
}

type PostEdge {
  cursor: String!
  node: Post!
}

type PageInfo {
  hasNextPage: Boolean!
  hasPreviousPage: Boolean!
  startCursor: String
  endCursor: String
}

type Query {
  posts(first: Int, after: String, last: Int, before: String): PostConnection!
}

A cursor is an opaque pointer to a position in the list (often a base64-encoded ID or timestamp). The client asks for first: 10, after: "cursor123" and the server returns the next ten plus a new endCursor. Because cursors point at stable positions rather than numeric offsets, inserts and deletes elsewhere in the list do not corrupt pagination. The edges/node indirection looks verbose, but it gives you a clean place to hang edge-specific metadata (like addedAt on a membership). Notably, the September 2025 conference introduced relative cursors, which aim to bring familiar "jump to page N" UX back to cursor pagination — a nice acknowledgment that pure cursors lost something offset pagination had.

Security: The Part You Cannot Skip

GraphQL's flexibility is a genuine attack surface. A client can request a deeply nested, wildly expensive query that REST's fixed endpoints would never allow. Treat these as non-negotiable for any public-facing graph.

Depth limiting. Reject queries nested beyond a sane threshold to stop pathological recursion like posts { author { posts { author { posts ... }}}}.

Query complexity / cost analysis. Assign a cost to fields and reject queries whose total exceeds a budget. Apollo Federation standardized a @cost(weight: Int!) directive and a @listSize directive to inform this analysis, so the gateway can score a query before executing it.

Rate limiting. Per-client limits, ideally weighted by query cost rather than raw request count, since one GraphQL request can do the work of fifty.

Disable introspection in production (or restrict it) so attackers cannot trivially map your entire schema, and turn off field suggestions that hint at valid field names.

Persisted (trusted) documents. Instead of accepting arbitrary queries, the client registers its queries ahead of time and at runtime sends only a hash. The server executes only known-good operations. At GraphQLConf 2025 the consensus was blunt: everyone serious is now using persisted/trusted documents, with raw arbitrary-query endpoints reserved for genuinely public APIs that accept the risk. This both shrinks the attack surface and slims the request payload.

Authentication and authorization belong in resolvers and context, not in the schema's existence. Authenticate the request once (populate context.user), then authorize per field or per resolver. Field-level auth — checking that the current user may see this specific field on this specific object — is more granular than REST's typical endpoint-level checks, which is both a feature and more code to get right.

Federation: GraphQL for Microservices

A single monolithic schema works until many teams need to own different parts of it. Federation lets you split one unified graph across multiple independently deployed services (subgraphs), composed by a gateway or router into a single graph the client sees.

Each subgraph owns its types and can extend types owned by others using directives like @key:

# Users subgraph
type User @key(fields: "id") {
  id: ID!
  name: String!
}

# Reviews subgraph — extends User without owning it
type User @key(fields: "id") {
  id: ID!
  reviews: [Review!]!
}

type Review {
  id: ID!
  body: String!
  author: User!
}

The router reads the query, figures out which subgraphs can resolve which fields, dispatches sub-queries to each, and stitches the results — all invisibly to the client, who just sees one User type with both name and reviews. Apollo Federation popularized this, and it has matured fast: recent Federation versions added directives like @cost, @listSize, and @cacheTag for response caching, and there is now a vendor-neutral Composite Schema Specification working group aiming to standardize federation so routers from different vendors interoperate. The router landscape itself is heating up, with high-performance Rust-based routers (Hive Router, Grafbase, Apollo's own) competing on latency and throughput.

Federation is powerful but it is not free — it adds a routing layer, schema composition checks in CI, and operational complexity. Reach for it when you genuinely have multiple teams owning distinct domains, not just because microservices sound modern.

Client-Side GraphQL

You can consume GraphQL with nothing but fetch — it is just a POST with a JSON body:

const res = await fetch("https://api.example.com/graphql", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    query: `query($id: ID!) { user(id: $id) { name } }`,
    variables: { id: "4" },
  }),
});
const { data, errors } = await res.json();

For real apps you want a client that handles caching, normalization, and request deduplication. Apollo Client is the heavyweight, with a normalized cache, React hooks, and (as of recent releases showcased in 2025) query preloading, Suspense integration, fragment APIs, and data masking. urql is lighter and more composable. Relay is the most opinionated and most powerful at scale, built around fragments and the Node interface, and is what Meta runs. Newer entrants like Houdini (Svelte-first) and Isograph push the component-data-colocation idea even further.

import { useQuery, gql } from "@apollo/client";

const GET_USER = gql`
  query GetUser($id: ID!) {
    user(id: $id) {
      name
      posts { title }
    }
  }
`;

function Profile({ id }) {
  const { loading, error, data } = useQuery(GET_USER, { variables: { id } });
  if (loading) return <Spinner />;
  if (error) return <Error message={error.message} />;
  return <h1>{data.user.name}</h1>;
}

The single biggest client-side productivity win is code generation. Tools like GraphQL Code Generator introspect your schema and your operations to produce fully typed hooks and result types. Your editor then autocompletes field names and your build fails if you query a field that does not exist. End-to-end type safety from database to UI, with the schema as the single source of truth, is a large part of why teams fall in love with GraphQL. The September 2025 major release of GraphQL Code Generator notably strengthened typing for both standard and federated servers.

Tooling and the 2026 Ecosystem

A quick tour of what you will actually touch.

GraphiQL and the embedded explorers in Apollo Studio / GraphOS give you an interactive, autocompleting query IDE backed by introspection — point it at any endpoint and start exploring. Schema registries track your schema over time and run composition and breaking-change checks in CI. The new Schema Coordinates feature from the September 2025 spec gives tooling a stable, canonical address for every field and type, which makes diffs, linting, and automated PR comments far more reliable.

Server libraries exist for essentially every language: Apollo Server, GraphQL Yoga, and Mercurius in JavaScript; graphql-java and DGS in Java; Strawberry and Graphene in Python; gqlgen in Go; async-graphql and Juniper in Rust; Hot Chocolate in .NET. Whatever your backend, there is a mature, idiomatic option.

One genuinely new development worth flagging: the September 2025 spec added descriptions on executable documents (queries, mutations, fragments — not just schema types). This sounds minor but it directly enabled GraphQL operations to be exposed as MCP tools for AI agents without custom infrastructure, since an operation can now carry a standardized, introspectable description of what it does. As AI tooling consumes APIs, a self-describing, strongly typed graph turns out to be an exceptionally good interface for machines as well as humans.

Best Practices and Common Pitfalls

A condensed field guide from teams who have shipped this in anger.

Design the schema for the client, not the database. Your schema is a product surface, not an ORM dump. Model the domain the way consumers think about it. Do not expose a users_posts_join table as a type.

Always solve N+1 from day one with DataLoader or your library's equivalent. It is not premature optimization; it is the default failure mode.

Model expected errors as typed schema results, reserve the top-level errors array for genuine exceptions, and never leak stack traces or internal messages to clients.

Use cursor-based pagination for any list that can grow, and adopt the Relay Connections shape so clients and tooling have a consistent contract.

Lock down public graphs with depth limits, cost analysis, persisted documents, and disabled introspection in production. Do this before launch, not after the incident.

Evolve additively and deprecate with @deprecated rather than versioning. Watch field usage in your registry before removing anything.

Adopt fragment colocation and codegen. Let components declare their own data needs and let generated types keep frontend and backend honest. This is where the developer-experience payoff compounds.

Do not reach for federation or subscriptions prematurely. Both are powerful and both add real operational weight. Start with a single well-designed schema and polling; graduate to federation when multiple teams demand ownership boundaries, and to subscriptions when polling genuinely cannot meet your real-time needs.

When to Adopt GraphQL

GraphQL is not a replacement for REST, a silver bullet, or a fad — it is now a mature, foundation-governed standard that received its first full spec edition since 2021 in September 2025, complete with input unions (@oneOf), schema coordinates, and operation descriptions. The ecosystem around it — Apollo, Relay, urql, federation routers in Rust, codegen, schema registries — is deep and production-hardened.

Reach for GraphQL when you have diverse clients with varied data needs, when you are aggregating multiple services behind one interface, when round-trip cost and over-fetching genuinely hurt, or when you want end-to-end type safety with the schema as the contract between teams. Stay with REST when your shapes are stable and simple, when HTTP/CDN caching is mission-critical, or when operational simplicity outweighs client flexibility.

If you do adopt it, internalize three things and you will avoid most of the pain: the schema is the contract, resolvers are where performance lives, and a public graph must be defended. Get those right and GraphQL delivers exactly what it promised back in 2012 — clients that ask for precisely what they need, and an API that grows without breaking.

Now go build something. Spin up Apollo Server with the blog schema above, point GraphiQL at it, and write your first query. The fastest way to understand the graph is to traverse it yourself.

GOOD NEWS FOR DEW

DevUnionX — Wed, 17 Jun 2026 21:20:44 +0000

DevUnionX

Jun 17

(Alert!)5 Things Even AI Can't Do, GraphQL

#graphql #ai #webdev #programming

19 min read

(Alert!)5 Things Even AI Can't Do, GraphQL

DevUnionX — Wed, 17 Jun 2026 21:19:59 +0000

GraphQL: A Complete Guide for Developers in 2026

NEWS: MY GAME JUST LAUNCHED

Flip Duel Card Battle - Apps on Google Play

Outsmart rivals in 1v1 card duels. Joker, bluff, ranked PvP. 5 rounds.

play.google.com

What GraphQL Actually Is

Here is the canonical hello-world. A query:

query {
  user(id: "4") {
    name
    email
    posts(last: 3) {
      title
    }
  }
}

And the response:

{
  "data": {
    "user": {
      "name": "Mary Watson",
      "email": "mary@example.com",
      "posts": [
        { "title": "On the Nature of APIs" },
        { "title": "Why I Stopped Versioning" },
        { "title": "Cursors, Not Offsets" }
      ]
    }
  }
}

The Problems GraphQL Solves

The flip side, which we will cover, is that GraphQL trades these wins for harder caching, a more involved server setup, and new categories of performance and security concern. There is no free lunch.

The Type System and Schema Definition Language

Let's build out a small blog API to make the type system concrete.

type User {
  id: ID!
  name: String!
  email: String
  role: Role!
  posts: [Post!]!
}

type Post {
  id: ID!
  title: String!
  body: String!
  published: Boolean!
  author: User!
  comments: [Comment!]!
}

type Comment {
  id: ID!
  text: String!
  author: User!
}

enum Role {
  ADMIN
  EDITOR
  READER
}

A few things to unpack here, because the syntax is dense with meaning.

Beyond objects and scalars, the type system has a few more tools you will reach for constantly.

Here is an interface and a union in practice:

interface Node {
  id: ID!
}

type Image implements Node {
  id: ID!
  url: String!
  altText: String
}

type Video implements Node {
  id: ID!
  url: String!
  durationSeconds: Int!
}

union SearchResult = User | Post | Image

input CreatePostInput {
  title: String!
  body: String!
  published: Boolean = false
}

Finally, the three special root operation types are the entry points into the entire graph:

type Query {
  user(id: ID!): User
  posts(published: Boolean): [Post!]!
  search(term: String!): [SearchResult!]!
}

type Mutation {
  createPost(input: CreatePostInput!): Post!
  deletePost(id: ID!): Boolean!
}

type Subscription {
  postPublished: Post!
}

Queries: Asking for Data

A query selects fields starting from the Query root and walking down the graph. The shape you write is the shape you get back.

query GetDashboard {
  posts(published: true) {
    id
    title
    author {
      name
    }
    comments {
      text
    }
  }
}

query GetUser($id: ID!, $postCount: Int = 10) {
  user(id: $id) {
    name
    posts(last: $postCount) {
      title
    }
  }
}

{ "id": "4", "postCount": 3 }

Aliases let you request the same field twice with different arguments, which would otherwise collide in the response object:

query {
  recent: posts(last: 5) { title }
  popular: posts(orderBy: VIEWS, last: 5) { title }
}

Fragments are reusable selection sets. They keep queries DRY and, more importantly, are the mechanism that powers component-colocated data requirements in modern clients:

fragment PostCard on Post {
  id
  title
  author { name }
}

query {
  posts(published: true) {
    ...PostCard
  }
}

Directives modify execution. The two built into the spec are @include and @skip, which conditionally add or remove fields:

query GetUser($id: ID!, $withPosts: Boolean!) {
  user(id: $id) {
    name
    posts @include(if: $withPosts) {
      title
    }
  }
}

Mutations: Changing Data

mutation PublishPost($input: CreatePostInput!) {
  createPost(input: $input) {
    id
    title
    published
  }
}

type CreatePostPayload {
  post: Post
  errors: [UserError!]!
}

type UserError {
  field: String
  message: String!
}

Subscriptions: Real-Time Data

Subscriptions push data to the client when an event occurs, rather than the client polling. They are the basis for live chat, notifications, collaborative editing, and dashboards.

subscription OnPostPublished {
  postPublished {
    id
    title
    author { name }
  }
}

Resolvers: Where the Work Happens

The schema describes what is possible. Resolvers are the functions that actually produce the data for each field. This is where GraphQL meets your real backend.

A resolver is a function that receives four arguments, conventionally (parent, args, context, info):

parent — the result of the parent field's resolver (also called root or source).
args — the arguments supplied to this field in the query.
context — a per-request object shared across all resolvers, ideal for the authenticated user, database connections, and loaders.
info — metadata about the execution state, including the requested fields. Rarely needed but powerful.

Here is a minimal server using Apollo Server, the most popular Node.js implementation, wired to the blog schema:

import { ApolloServer } from "@apollo/server";
import { startStandaloneServer } from "@apollo/server/standalone";

const typeDefs = `#graphql
  type User {
    id: ID!
    name: String!
    posts: [Post!]!
  }
  type Post {
    id: ID!
    title: String!
    author: User!
  }
  type Query {
    user(id: ID!): User
    posts: [Post!]!
  }
`;

const resolvers = {
  Query: {
    user: (parent, args, context) => context.db.getUser(args.id),
    posts: (parent, args, context) => context.db.getPosts(),
  },
  User: {
    posts: (parent, args, context) => context.db.getPostsByAuthor(parent.id),
  },
  Post: {
    author: (parent, args, context) => context.db.getUser(parent.authorId),
  },
};

const server = new ApolloServer({ typeDefs, resolvers });

const { url } = await startStandaloneServer(server, {
  context: async ({ req }) => ({
    db: database,
    user: await authenticate(req.headers.authorization),
  }),
  listen: { port: 4000 },
});

console.log(`Server ready at ${url}`);

The Request Lifecycle

Understanding what the server does with an incoming operation demystifies a lot of behavior and performance characteristics. Every request goes through three phases.

Parsing. The raw query string is tokenized and turned into an Abstract Syntax Tree (AST). Syntax errors are caught here before anything else runs.

The N+1 Problem and DataLoader

Now the most important performance pitfall in GraphQL, the one that bites every team eventually.

Recall the nested resolver model. Consider this query:

query {
  posts {       # 1 query: fetch 50 posts
    title
    author {    # runs once PER post: 50 more queries!
      name
    }
  }
}

import DataLoader from "dataloader";

function createUserLoader(db) {
  return new DataLoader(async (userIds) => {
    // userIds = ['1', '7', '7', '12', ...] collected across all 50 author resolvers
    const users = await db.getUsersByIds(userIds);
    const byId = new Map(users.map((u) => [u.id, u]));
    // must return results in the SAME ORDER as the input keys
    return userIds.map((id) => byId.get(id));
  });
}

// create a fresh loader per request, in context
const server = new ApolloServer({ typeDefs, resolvers });
startStandaloneServer(server, {
  context: async () => ({
    userLoader: createUserLoader(database),
  }),
});

// resolver now uses the loader
const resolvers = {
  Post: {
    author: (post, args, context) => context.userLoader.load(post.authorId),
  },
};

GraphQL vs REST: An Honest Comparison

Neither wins universally. Here is how they actually stack up.

Many mature organizations run both: REST for simple service-to-service and public endpoints, GraphQL as the client-facing aggregation layer. It is not a religious war.

Pagination Done Right

type PostConnection {
  edges: [PostEdge!]!
  pageInfo: PageInfo!
}

type PostEdge {
  cursor: String!
  node: Post!
}

type PageInfo {
  hasNextPage: Boolean!
  hasPreviousPage: Boolean!
  startCursor: String
  endCursor: String
}

type Query {
  posts(first: Int, after: String, last: Int, before: String): PostConnection!
}

Security: The Part You Cannot Skip

Depth limiting. Reject queries nested beyond a sane threshold to stop pathological recursion like posts { author { posts { author { posts ... }}}}.

Rate limiting. Per-client limits, ideally weighted by query cost rather than raw request count, since one GraphQL request can do the work of fifty.

Disable introspection in production (or restrict it) so attackers cannot trivially map your entire schema, and turn off field suggestions that hint at valid field names.

Federation: GraphQL for Microservices

Each subgraph owns its types and can extend types owned by others using directives like @key:

# Users subgraph
type User @key(fields: "id") {
  id: ID!
  name: String!
}

# Reviews subgraph — extends User without owning it
type User @key(fields: "id") {
  id: ID!
  reviews: [Review!]!
}

type Review {
  id: ID!
  body: String!
  author: User!
}

Client-Side GraphQL

You can consume GraphQL with nothing but fetch — it is just a POST with a JSON body:

const res = await fetch("https://api.example.com/graphql", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    query: `query($id: ID!) { user(id: $id) { name } }`,
    variables: { id: "4" },
  }),
});
const { data, errors } = await res.json();

import { useQuery, gql } from "@apollo/client";

const GET_USER = gql`
  query GetUser($id: ID!) {
    user(id: $id) {
      name
      posts { title }
    }
  }
`;

function Profile({ id }) {
  const { loading, error, data } = useQuery(GET_USER, { variables: { id } });
  if (loading) return <Spinner />;
  if (error) return <Error message={error.message} />;
  return <h1>{data.user.name}</h1>;
}

Tooling and the 2026 Ecosystem

A quick tour of what you will actually touch.

Best Practices and Common Pitfalls

A condensed field guide from teams who have shipped this in anger.

Always solve N+1 from day one with DataLoader or your library's equivalent. It is not premature optimization; it is the default failure mode.

Model expected errors as typed schema results, reserve the top-level errors array for genuine exceptions, and never leak stack traces or internal messages to clients.

Use cursor-based pagination for any list that can grow, and adopt the Relay Connections shape so clients and tooling have a consistent contract.

Lock down public graphs with depth limits, cost analysis, persisted documents, and disabled introspection in production. Do this before launch, not after the incident.

Evolve additively and deprecate with @deprecated rather than versioning. Watch field usage in your registry before removing anything.

When to Adopt GraphQL

Now go build something. Spin up Apollo Server with the blog schema above, point GraphiQL at it, and write your first query. The fastest way to understand the graph is to traverse it yourself.

5 Things Even AI Can't Do, REST API

DevUnionX — Wed, 27 May 2026 01:22:59 +0000

Roy Fielding Would Like a Word About Your "REST API"

In October 2008, Roy Fielding — the person who literally invented REST in a year 2000 PhD dissertation, the same person who co-authored HTTP — opened a blog post with this sentence:

I am getting frustrated by the number of people calling any HTTP-based interface a REST API.

He then proceeded, over about a thousand words, to roast the entire industry for calling things REST that were not, in fact, REST. The line that everyone still quotes, eighteen years later:

That is RPC. It screams RPC. There is so much coupling on display that it should be given an X rating.

Reader, I have built dozens of APIs in my career that I called REST APIs, that were not REST APIs by Fielding's definition. You probably have too. Almost every "REST API" you have ever used is, by the inventor's own standard, not REST. And the industry has collectively decided that's fine, and we use the word REST anyway, and Fielding is presumably still grumpy about it from his office in California.

This article is the long version of what REST actually is, what people mean when they say REST in 2026, the difference between the two, and the daily-practice details — status codes, idempotency, pagination, error formats, versioning — that you actually need to get right whether you call your API REST or REST-ish or HTTP+JSON or whatever you want to call it. Get coffee. There's a lot of ground to cover.

The Dissertation Nobody Read

Roy Thomas Fielding's PhD dissertation, Architectural Styles and the Design of Network-based Software Architectures, was published at UC Irvine in 2000. It is 180 pages long. Chapter 5 is titled "Representational State Transfer (REST)" and it's where the term came from. If you've never read it, that's fine — almost nobody has. But you should know it exists, because every argument about whether something is "really REST" eventually comes back to this document.

The setup matters. Fielding wrote the dissertation while he was simultaneously co-authoring the HTTP/1.1 specification and the URI standards at the IETF. He wasn't theorizing about the web from the outside. He was building the web while he was writing about how the web should work. That's why REST has the authority it has — the person who defined the style was also one of the people defining the protocol it runs on.

REST, per Fielding, is defined by six constraints. Five are mandatory, one is optional:

Client–Server — separation of concerns. The client and the server evolve independently.
Stateless — every request contains all the information needed to understand it. The server stores no client session state.
Cacheable — responses must declare themselves cacheable or not.
Uniform Interface — this is the big one. We'll get to it.
Layered System — clients can't tell whether they're talking to the origin server or an intermediary.
Code on Demand (optional) — the server can send executable code to extend the client.

That fourth one, the uniform interface, has four sub-constraints, and this is where the industry quietly stopped following the rules:

Identification of resources
Manipulation of resources through representations
Self-descriptive messages
Hypermedia as the engine of application state

That last sub-constraint has an acronym: HATEOAS. It means that a REST API's responses should contain links — hypermedia — telling the client what it can do next. Like a webpage. You don't memorize URLs to navigate a website; you click links. A real REST API works the same way: the client starts at one entry point, gets back a response with links, and follows those links to navigate the application.

Almost no API you have ever used works this way.

The 2008 Rant That Aged Like Wine

By 2008, "REST" had become an industry buzzword. Every company was launching a "REST API" — by which they meant they had endpoints that returned JSON. Fielding watched this happen for a few years and then snapped. The October 20, 2008 post titled "REST APIs must be hypertext-driven" is the foundational document of every "well actually, that's not really REST" argument that has happened on Twitter since.

Some choice cuts:

if the engine of application state (and hence the API) is not being driven by hypertext, then it cannot be RESTful and cannot be a REST API. Period.

In the comments, he doubled down:

A truly RESTful API looks like hypertext.

And the line that I think about the most, also from the comments:

REST is software design on the scale of decades: every detail is intended to promote software longevity and independent evolution. Many of the constraints are directly opposed to short-term efficiency.

That last sentence is, I think, the real reason HATEOAS lost. Engineers under deadline pressure don't optimize for decades. They optimize for the next sprint. HATEOAS makes APIs more resilient over very long time horizons at the cost of immediate complexity. So we all just shipped Level 2.

The Richardson Maturity Model

A better way to think about REST in practice comes from Leonard Richardson, who presented the Richardson Maturity Model in 2008 — coincidentally the same year as Fielding's rant. Martin Fowler wrote it up on his blog and it stuck. It's the most useful diagnostic tool in the industry.

Level 0 — "The Swamp of POX." You have one URL. Everything is a POST. The request body decides what happens. This is SOAP. This is /api/endpoint taking { "action": "getUser", "id": 123 }. This is the bottom.

Level 1 — Resources. You have distinct URIs for distinct things. /users, /orders/42. You might still POST everything, but at least the URLs identify resources.

Level 2 — HTTP Verbs. You use GET for reading, POST for creating, PUT for replacing, PATCH for partial updates, DELETE for deleting. You return proper status codes — 200 for success, 404 for not found, 500 when you've broken. This is where Stripe lives. This is where GitHub lives. This is where every "REST API" you've used lives. This is what 99% of the industry calls "REST."

Level 3 — Hypermedia controls (HATEOAS). Every response embeds links telling the client what actions are possible next. The client navigates the API by following links, not by constructing URLs from memory.

Fielding's 2008 post is, basically, a protest that nothing below Level 3 should be called REST. Richardson's model is more diplomatic — it gives you a ladder, lets you see where you are, and doesn't insist you climb all the way up.

The industry stopped at Level 2 and renamed it REST. That's the whole story. Everything from here on out is just the engineering details of doing Level 2 well.

What "REST API" Actually Means In 2026

Let me give you the honest, working developer's definition. A "REST API" in 2026 is an API that:

Uses HTTP as its transport
Returns JSON (almost never XML anymore)
Has resource-oriented URLs — nouns, not verbs (/users/123, not /getUser?id=123)
Uses HTTP verbs correctly (GET reads, POST creates, etc.)
Returns standard HTTP status codes that aren't lying
Is documented, ideally with OpenAPI

That's it. That's the definition that 99% of engineers carry in their heads and 99% of working APIs satisfy. It is, strictly speaking, Level 2 on the Richardson scale. It is, strictly speaking, not REST per Fielding. Nobody cares.

The reason we still call it REST is that the alternative names are worse. "HTTP+JSON API" is accurate but clumsy. "REST-ish" is honest but apologetic. "Web API" is too broad. "RESTful" is a fig leaf — it signals "we know we're not quite REST but please give us partial credit." So we say REST, everyone knows what we mean, and we move on.

HTTP Verbs and the Idempotency Religion

Here's the verb cheat sheet you actually need:

GET — read a resource. Idempotent. Safe. Cacheable. Don't put side effects here. Yes, I know your tracking pixel does. Don't.
POST — create a resource, or "do a thing." Not idempotent.
PUT — replace a resource entirely. Idempotent.
PATCH — partially update a resource. Can be idempotent if you design it that way; often isn't.
DELETE — delete a resource. Idempotent.

The word "idempotent" gets thrown around like everyone agrees what it means, so let me state it cleanly: a request is idempotent if making it N times produces the same server state as making it once. Deleting the user with ID 42 ten times leaves you with the same state as deleting them once — they're gone. So DELETE is idempotent. POSTing "create a new order" ten times creates ten orders. So POST is not idempotent.

Why does this matter? Because networks are unreliable. Your client sends a request, the network drops the response, the client doesn't know if the request succeeded or not. If the request was idempotent, retrying is safe. If not, retrying might charge your customer twice.

Stripe has the canonical solution to this and it's worth knowing by heart. They use an HTTP header called Idempotency-Key. The client generates a unique key (a UUID, typically) and sends it with the request:

curl https://api.stripe.com/v1/charges \
  -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
  -H "Idempotency-Key: AGJ6FJMkGQIpHUTX" \
  -d amount=2000 -d currency=usd

The server stores the result of the first request under that key for a window (24 hours for Stripe v1, 30 days for v2). If the same key comes in again, the server returns the cached result instead of charging the customer again. The client can retry as many times as it wants without fear of double-charging.

Brandur Leach's "Designing robust and predictable APIs with idempotency" on the Stripe engineering blog is required reading if you're building anything that touches money. The pattern works for any non-idempotent operation, not just payments.

Status Codes That Actually Matter

There are sixty-something HTTP status codes. You need to know about fifteen of them. Here's the working set:

200 OK — Success, with a body. The default for GET, PUT, and PATCH responses.

201 Created — A new resource was created. Should include a Location header pointing to the new resource. Useful for POSTs that create something.

204 No Content — Success, intentionally empty body. The spec says you cannot send a body with a 204. The natural answer for DELETE and for PUTs that don't need to echo back the updated resource. People argue endlessly about whether DELETE should return 200 (with the deleted entity in the body) or 204 (with nothing). Both are defensible. Pick one and be consistent.

301 Moved Permanently — Useful for URL versioning migrations. The browser caches this aggressively, so be careful.

400 Bad Request — The client sent garbage. Malformed JSON, missing required fields, that sort of thing.

401 Unauthorized — You aren't authenticated. The spec calls this "Unauthorized" but it really means "Unauthenticated." Everyone gets this wrong because the name is bad.

403 Forbidden — You ARE authenticated, but you don't have permission to do this thing. The "you can't sit with us" of HTTP.

404 Not Found — The resource doesn't exist. GitHub famously returns 404 for private repositories you don't have access to, instead of 403, to avoid leaking information about what exists. That's a defensible third path between 403 and 404.

409 Conflict — State conflict. Duplicate keys, version mismatches, "this email is already taken."

422 Unprocessable Content — Your JSON parsed fine, but it's semantically wrong. Validation failures, basically. This started as a WebDAV-specific code and got repurposed by the industry because there was a gap between "syntactically broken" (400) and "logically wrong" (which previously had no good code).

429 Too Many Requests — Rate limited. Defined by RFC 6585 in April 2012. You should include a Retry-After header telling the client how long to wait.

500 Internal Server Error — We broke.

502 Bad Gateway — Our upstream broke.

503 Service Unavailable — We're down or overloaded. Include Retry-After if you know when you'll be back.

The 401 vs 403 confusion is something I've watched senior engineers get wrong, repeatedly, on production systems. The mnemonic: 401 means "who are you," 403 means "I know who you are, no."

URL Design: The Trailing Slash and Other Religious Debates

Resource-oriented URLs use nouns, not verbs. GET /users/123/posts is good. GET /getUserPosts?id=123 is bad. This is one of the few things the entire industry agrees on.

Use plurals for collections. /users, not /user. The Microsoft API guidelines, Google's API guidelines, Zalando's guidelines, and basically everyone else agree. Yes, "/people" is more grammatically correct than "/persons," but consistency beats correctness — pick the rule "always plural" and apply it uniformly.

For nested resources, prefer two-level nesting at most. /users/123/posts is fine. /users/123/posts/456/comments/789/reactions/abc is hardcoding your data model into your URLs in a way you will regret. The pragmatic alternative: /comments/789/reactions or /reactions?comment_id=789.

Now the trailing slash. /users versus /users/. People have died on this hill. John Sheehan of Runscope said it best, and the API Evangelist quoted him: save the byte, drop the slash, and 301-redirect from the slashed version to the non-slashed version if anyone hits it. That's the pragmatic answer. By the strict reading of Fielding's dissertation, URIs are character-by-character identifiers, which means /users and /users/ are different resources unless the server normalizes them. In practice, your framework probably normalizes them and nobody on your team will ever notice.

Versioning Is A Mess

There is no good answer here. There are three answers, all bad in different ways.

URL versioning (/v1/users, /v2/users) is what Stripe does, what most pragmatic teams do, and what I'd recommend for new APIs. It's discoverable. It's debuggable in a browser tab. It's obvious in logs. The downside is that the URL of a resource is supposed to be the identity of the resource, and /v1/users/42 and /v2/users/42 are arguably the same user with different representations, which is what content negotiation is for. But almost nobody cares about this in practice.

Header versioning (X-API-Version: 2) keeps URLs clean and lets you handle versions via middleware. GitHub does this with calendar-based versioning — their header is X-GitHub-Api-Version: 2022-11-28, and in March 2026 they released their first calendar version with breaking changes, 2026-03-10. Stripe also uses dated versions, like 2025-12-15.clover. The calendar-based approach has the nice property that "v2" doesn't have to mean "we changed everything" — each release is a small, dated diff from the previous.

Content negotiation (Accept: application/vnd.myapi.v2+json) is the "by the book" REST answer. Almost nobody uses it because debugging an API in a browser tab is impossible when you have to set custom Accept headers. It exists. You can ignore it.

If I'm building a new API in 2026 and I have no constraints, I pick calendar-based versioning in a header, like GitHub. If I'm building something simpler and I want minimum friction, I pick /v1/ in the URL and live with it.

Pagination Has No Standard

There is no RFC for pagination. There is no IETF spec. There is no industry agreement. Every API does it differently. This is genuinely embarrassing and I don't expect it to be fixed in my career.

The four approaches in the wild:

Offset/limit (?offset=20&limit=10). Simple. You can jump to page 47. But if data shifts under you — someone inserts or deletes a row — you'll see duplicates or skips. Performance falls off a cliff at high offsets because the database has to count past all the previous rows.

Cursor-based (?cursor=eyJpZCI6MTAwfQ&limit=10). The cursor is an opaque base64-encoded token that the server understands. Stable under inserts. You can't jump to an arbitrary page, but that's usually fine — infinite scroll doesn't need page jumping. Stripe uses this. Slack uses this. GitHub uses this for several endpoints. This is the right answer for most APIs.

Keyset (?after_id=100). A non-opaque cursor based on an indexed column. Slightly less flexible than opaque cursors but easier to debug.

Page-based (?page=3&per_page=10). Cosmetic offset/limit. Same problems.

Zalando's API guidelines recommend cursors for anything more than a few hundred items. I agree. If your collection might exceed a thousand items, use cursors. If it's always small (a user's recent orders, say), offset/limit is fine.

There's a beautiful idea, almost never implemented in practice, of putting pagination links in HTTP headers via RFC 8288 (the Web Linking spec):

Link: <https://api.example.com/items?page=3>; rel="next",
      <https://api.example.com/items?page=10>; rel="last"

GitHub has done this since their V3 days. It's elegant — the URLs are right there, the client doesn't have to construct them. Nobody else does it because most clients don't parse Link headers automatically and most developers don't think to look.

Error Responses: RFC 7807 Exists And Almost Nobody Uses It

In March 2016, Mark Nottingham (of Akamai, also known for the HTTP cache header Cache-Control) and Erik Wilde published RFC 7807, "Problem Details for HTTP APIs." In July 2023 it was updated as RFC 9457. The media type is application/problem+json. Here's what an RFC-7807-compliant error response looks like:

HTTP/1.1 404 Not Found
Content-Type: application/problem+json

{
  "type": "https://api.example.com/problems/user-not-found",
  "title": "User Not Found",
  "status": 404,
  "detail": "User with ID 12345 does not exist",
  "instance": "/users/12345"
}

Five fields. type is a URI identifying the kind of problem (which the client can recognize and handle programmatically). title is a short human-readable name. status echoes the HTTP status. detail is a longer human-readable explanation. instance is the URI of this specific occurrence.

It's elegant. It's standardized. It's been around for almost a decade. ASP.NET Core ships it by default. Spring Boot has built-in support. And almost nobody outside those two ecosystems uses it. Instead, every API invents its own error format:

// Common
{ "error": "User not found" }

// Also common
{ "errors": [{ "code": "USER_NOT_FOUND", "message": "..." }] }

// Why did anyone do this
{ "success": false, "data": null, "error": { "msg": "..." } }

// The cardinal sin — 200 OK with this body
{ "ok": false, "error": "Something went wrong" }

That last one — returning HTTP 200 with an error in the body — is the worst pattern in REST and Facebook's Graph API did it for years. Every middleware, every load balancer, every monitoring tool understands HTTP status codes. When you return 200 for an error, you've thrown away your ability to alert on errors, retry intelligently, or cache responses. You've made every client write a custom error handler that ignores the status code and reads the body. Please don't.

If you're building a new API, use RFC 7807 / 9457. The format is good. The standard exists. You don't have to invent error handling from scratch.

Authentication: The Real Cheat Sheet

You have basically five options. Pick the right one for your situation:

API keys are the simplest thing that works. Send Authorization: Bearer sk_live_abc123 in the header. Stripe does this. It works. The downside is that the key has all-or-nothing access (no scopes), and if it leaks, you have a problem. Don't put keys in URLs — they end up in server logs, browser history, and analytics tools. Header only.

Basic Auth (Authorization: Basic <base64(user:pass)>) is older than the web you grew up with. It's still everywhere, especially for internal services and webhook signing. It's fine. It's not great. Use HTTPS or die.

OAuth 2.0 is the right answer for any API that third parties will integrate with. The flows that actually matter in 2026:

Authorization Code with PKCE — the default for SPAs and mobile apps. PKCE (Proof Key for Code Exchange, RFC 7636) is now effectively mandatory under the OAuth 2.1 draft and RFC 9700's security best practices. Even Anthropic's Model Context Protocol adopted OAuth 2.1 for tool authorization.
Client Credentials — for server-to-server, where there's no user.
Refresh Token Rotation — for keeping SPAs logged in despite browser cookie restrictions.

JWT bearer tokens are a love/hate relationship. They're self-contained (no DB lookup needed to validate), but you can't revoke them without building a denylist, which defeats the point of having them be self-contained. The right framing: JWTs are great for short-lived access tokens (15 minutes), terrible as long-lived session tokens. If your JWT lives for 30 days, you've reinvented session cookies, badly.

Session cookies are still completely valid in 2026, often the right answer for first-party web apps, and unjustly maligned by everyone who reaches for JWTs out of habit. They have a security story (HttpOnly, Secure, SameSite) that's been honed for thirty years. Use them when they fit.

PUT vs PATCH: The Confusing One

PUT replaces the resource entirely. If the resource was { name: "Jane", email: "j@example.com", role: "admin" } and you PUT { name: "Jane Doe" }, the resource is now { name: "Jane Doe" } — the email and role are gone, because PUT replaces.

PATCH applies a partial update. If you PATCH { name: "Jane Doe" } to the same resource, the result is { name: "Jane Doe", email: "j@example.com", role: "admin" } — only the name changed.

That's the conceptual difference. The complication is that there are two competing formats for PATCH, and APIs that don't tell you which one they use will make you cry.

JSON Patch (RFC 6902), media type application/json-patch+json, is an array of operations:

[
  { "op": "replace", "path": "/email", "value": "new@example.com" },
  { "op": "remove",  "path": "/nickname" }
]

It's atomic, expressive, and lets you address individual array indices. It's also unreadable. Nobody writes these by hand.

JSON Merge Patch (RFC 7396), media type application/merge-patch+json, looks like the object you want, with null meaning "delete":

{
  "email": "new@example.com",
  "nickname": null
}

It's intuitive. You can write it by hand. But you cannot use it to set a field to literal null, and you cannot update individual array indices — you can only replace the whole array.

GitHub uses Merge Patch–style. Kubernetes supports three different patch types — JSON Patch, Merge Patch, and a custom Strategic Merge Patch — because of course Kubernetes does. If you're building a new API and don't have strong opinions, use Merge Patch. It's simpler, and the limitations rarely matter in practice.

Rate Limiting and Caching

Rate limiting in HTTP is 429 Too Many Requests plus the Retry-After header. The RFC 6585 definition is straightforward, but the headers used to communicate quota state are not standardized. The convention everyone uses (without an RFC) is:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 47
X-RateLimit-Reset: 1714232400

There's an IETF draft (draft-ietf-httpapi-ratelimit-headers) that proposes the same headers without the X- prefix, but it's been a draft for years. If you implement rate limiting, set both Retry-After (which is standardized) and the X-RateLimit headers (which are conventional). Your clients will thank you.

The right retry strategy on the client side is exponential backoff with jitter: delay = min(cap, base * 2^attempt) + random(0, jitter). The jitter matters more than you'd think — without it, all your clients retry at exactly the same moment after a 429 storm, and you get a thundering herd.

Caching is Cache-Control, ETag, Last-Modified, and the conditional request headers (If-None-Match, If-Modified-Since). The honest truth is that almost nobody uses HTTP caching properly for JSON APIs. The reason is that in a modern stack, you have a CDN in front (handling its own caching), an application cache in Redis (handling server-side), and a client-side cache in the browser (React Query, SWR, Apollo, TanStack Query). HTTP-level caching feels like a fourth layer that doesn't pay off, and most APIs ship Cache-Control: no-store for everything authenticated.

It's a missed opportunity but I understand why it happened.

The Competing Paradigms (Brief Tour)

REST isn't the only game in town. Quick survey of the alternatives, why they exist, and why REST is still the default:

GraphQL (Facebook, 2015) solves over-fetching and under-fetching. You ask for exactly the fields you want, you get exactly those fields. Great for complex frontends with diverse data needs. Terrible operational story: caching is hard, query complexity attacks are a real concern, N+1 resolver storms unless you use DataLoader, and the bundle weight of Apollo Client is non-trivial. Use it when your client teams genuinely need flexible queries. Skip it when you're just doing CRUD.

gRPC (Google, 2015) is Protocol Buffers over HTTP/2. Binary, fast, schema-first, with code generation for every major language. The current stable version as of early 2026 is gRPC 1.80.0 (released March 30, 2026). Benchmarks vary but you can expect roughly an order of magnitude smaller payloads than equivalent JSON, and meaningful latency wins for chatty internal services. The catch: browsers can't speak it natively, so for browser-facing APIs you need grpc-web plus a proxy. Use it for east-west service-to-service communication, especially at scale. Don't bother for public APIs.

tRPC is TypeScript-only RPC where your TypeScript types are the contract. No schema, no codegen, no OpenAPI. Tiny bundle (around 5KB). If you're shipping a TypeScript monorepo with a Next.js frontend and a Node backend, it eliminates a whole layer of contract management. Useless outside the TypeScript ecosystem.

Server-Sent Events (SSE) is one-way streaming from server to client over plain HTTP. The browser supports it natively through EventSource. This is what OpenAI and Anthropic use to stream AI tokens. It's underrated. If you need streaming and you don't need bidirectional, use SSE before reaching for WebSockets.

WebSockets are full-duplex, separate protocol after an HTTP upgrade. For chat, multiplayer games, real-time collaboration. Overkill for most uses.

AsyncAPI is the specification for documenting event-driven APIs (Kafka, MQTT, AMQP, WebSockets, etc.) — the equivalent of OpenAPI but for messages instead of requests. Current version is 3.1.0, released January 31, 2026.

Why is REST still the default in 2026 despite all of this? Because it's the lowest common denominator. Every language has an HTTP client. Every developer can curl your API. Every API gateway, CDN, monitoring tool, and WAF understands HTTP+JSON for free. The cost of "more correct" alternatives is real and often not worth paying for typical CRUD workloads.

The 2026 Angle: AI Agents Read Your API

Here's the new thing in 2026 that wasn't a thing five years ago: LLM agents consume APIs. They read the OpenAPI spec, they figure out the tools available, they make the calls themselves. Google's Agent Development Kit has OpenAPIToolset. The FastMCP library has FastMCP.from_openapi(). Anthropic's Model Context Protocol standardizes the tool-discovery layer that bridges LLMs and APIs.

OpenAPI 3.2.0 (dated September 19, 2025) added native streaming media types — SSE, JSON Lines, multipart feeds — exactly because AI workloads need them. The OpenAPI Initiative has explicitly oriented the spec toward AI consumption.

What this means for API designers: your API documentation is now an LLM-readability concern. Vague operation IDs, missing descriptions, chatty endpoints with poor schemas — these used to be human-only problems. Now they cause AI agents to hallucinate, misuse your API, or fail to use it at all. Good operation names (createUser, not endpoint_v2_user_create_new), thorough descriptions, well-typed request and response schemas, and clear error responses are no longer nice-to-have. They are the difference between an LLM agent that can use your API and one that can't.

If you maintain a public API, generating high-quality OpenAPI 3.2 specs is probably the highest-leverage investment you can make in 2026. The audience for your docs now includes machines.

The Mistakes I Have Watched Get Made In Production

Permit me a personal list. Every one of these I have either shipped myself or watched a colleague ship:

POST for everything. I have seen POST /api/getUser in production. At three different unicorns. Yes, in production. There is no excuse. Use GET for reads.

HTTP 200 with { "success": false, "error": "..." }. Throws away every benefit of HTTP status codes. Breaks monitoring, breaks caching, breaks retries.

Inconsistent casing in the same response. { "userId": 1, "user_name": "alice" }. This happens. Usually because the field was added by a different team that hadn't read the style guide.

Verbs in URLs. /getUser, /createOrder, /deleteAccount. Verbs go in the HTTP method. That is literally what HTTP methods are for. If your URL has /get or /create or /delete in it, you're doing RPC and you should at least be honest about it.

No pagination on collection endpoints. Until one customer has 50,000 invoices, and then your API times out, and then you spend a sprint adding pagination retrofit. Add pagination from day one, even if you don't think you'll need it.

Ignoring idempotency for create operations. Network blip, double-charged customer, angry email at 2am. Use Stripe's pattern. Implement idempotency keys.

Massive nested URLs. /users/:id/orders/:orderId/items/:itemId/notes/:noteId. You've now hardcoded your data model into your URL structure. When the data model changes, every URL is a breaking change. Flatten where possible.

Not using HTTP cache headers, even when you could. Public, read-heavy endpoints can absolutely use proper Cache-Control and ETag responses. The CDN will love you. Your origin will love you. Your bill will love you.

Versioning policy of "we'll figure it out later." Then later arrives, you have ten thousand customers depending on v1, and you can't change anything without breaking the world. Adopt calendar versioning from day one, or commit to URL versioning with a clear deprecation policy. Either is fine. Both beat nothing.

The Two Reference APIs You Should Read

If you want to learn what good REST API design looks like, there are two public APIs to study.

Stripe is the canonical "good REST API." Their own docs put it plainly: the Stripe API is organized around REST, with predictable resource-oriented URLs, form-encoded bodies, JSON responses, standard HTTP status codes, and standard HTTP authentication. The little details matter — typed prefixes for object IDs (cus_ for customers, pi_ for payment intents, in_ for invoices), the Idempotency-Key header pattern, the expand[] query parameter for embedding related resources (avoiding N+1 round trips), the dated version strings. Read the docs. Steal liberally.

GitHub is the canonical "evolved over a decade and shows it." The API has been alive since around 2008. It's been through multiple versioning schemes, multiple authentication paradigms, multiple pagination styles. It's a museum of every fashion in REST API design since the late 2000s, all coexisting in one product, none of them quite consistent with each other. Read it as a cautionary tale about what happens when you don't decide on conventions early and stick to them.

Stripe and GitHub between them will teach you 90% of what you need to know about REST API design in practice. Read them. Compare them. Notice what Stripe got right that GitHub didn't. Then go design your own API with that knowledge.

Tooling You Should Actually Be Using

The 2026 tooling landscape:

For API documentation: OpenAPI 3.2.0. Generate it from your code (FastAPI, tRPC's OpenAPI plugin, NestJS, Spring) or write it by hand and use it to generate code (openapi-generator, Stainless, Speakeasy, Fern, Kiota). Either direction works. Pick one.

For API exploration: Postman is still #1 but increasingly hated for cloud-sync requirements and pricing. Insomnia got acquired by Kong and lost mindshare. Bruno is the breakout 2024 alternative — open-source, MIT-licensed, stores collections as plain-text files on disk for proper Git workflows, no cloud, no login, no telemetry. As of early 2026 it has around 41,000 GitHub stars and is what most developers I know have switched to. Hoppscotch is the lightweight browser-first option.

For API mocking: MSW (Mock Service Worker) for frontend tests. Prism for mock servers from OpenAPI specs.

For API linting: Spectral, from Stoplight. Catches inconsistencies, enforces house style. Put it in CI.

For the command line: curl for everything serious. HTTPie if you want commands to read like English (http POST api.example.com/users name=alice).

That's it. Five tools cover 99% of API workflows. Don't overthink your tooling.

The Closing Argument

I've written this article in a slightly grumpy mood because I think the gap between Fielding's REST and what we call REST is one of the most interesting stories in modern software, and most articles on the topic skip it entirely. The honest version is that we — the industry — borrowed a term, simplified it, and built something useful but not what the inventor meant. Whether that's fine or a sin against software longevity depends on how much you take Fielding's "decades-scale design" seriously.

Personally, I think it's fine. HATEOAS was a beautiful idea that didn't survive contact with the average engineering team's quarterly priorities. The Level 2 industry standard — HTTP+JSON with proper verbs and status codes — has shipped countless functional systems that work well enough for their lifespans. The cost of doing real REST was higher than the benefit for most teams. So we did the cheaper thing and called it REST anyway. The web didn't end.

But the details still matter. Use the right HTTP verb. Return honest status codes. Don't return 200 with an error in the body. Use cursor-based pagination for large collections. Implement RFC 7807 problem details for errors. Pick a versioning strategy and commit to it. Add idempotency keys for non-idempotent writes. Generate good OpenAPI specs because the LLMs are reading them now too. These are the things that separate an API your customers love from one they have to write a wrapper library around.

Roy Fielding probably still doesn't think any of this is REST. But if we get the daily details right, our APIs are going to outlive us anyway, which was the point.

Now go fix the one in your repo that returns 200 with { "success": false }. You know which one.

?

DevUnionX — Sat, 09 May 2026 11:48:28 +0000

DevUnionX

May 9

5 Things AI Can't Do, Even in Cypress

#test #react #webdev #programming

22 min read

5 Things AI Can't Do, Even in Cypress

DevUnionX — Sat, 09 May 2026 11:47:59 +0000

I Wrote 800 Cypress Tests. Then Playwright Came Out. Here's the Honest Story.

The first Cypress test I ever wrote was a login flow for a SaaS dashboard sometime in late 2019. I had spent the previous week wrestling with Selenium and a flaky Chromedriver, and a colleague kept telling me to "just try Cypress, it's different." I installed it, ran npx cypress open, and a window popped up showing my actual application running next to a list of commands, and I could click any command in the sidebar and watch the DOM rewind to that exact moment.

I think I said "oh" out loud. The kind of "oh" that means a tool just made a problem you'd been brute-forcing for years go away.

For the next four years, Cypress was the tool. Not "a tool we considered" the tool. We had eight hundred tests. We had a Cypress Cloud subscription. We had custom commands for everything. We had a wiki page called "How to debug a flaky Cypress test" that was longer than most onboarding documents. I gave talks about Cypress at meetups. I argued for Cypress in code review. I was a Cypress person.

And then, one Tuesday in mid-2024, I sat down to write a test for a feature that opened a popup window, and I remembered for what felt like the hundredth time that Cypress can't open a second tab. And I looked at the Playwright docs that I had been deliberately avoiding for two years, because deep down I knew what I would find. And I found it.

This article is the long version of what I found. It's also a love letter, because Cypress is genuinely a brilliant piece of software and the philosophy behind it changed how I think about testing. But it's an honest love letter, which means it has to acknowledge that the world has moved. As of April 2026, Playwright has roughly seven times Cypress's weekly npm downloads. The crossover happened in June 2024. There are real reasons that happened, and there are also real reasons Cypress is still installed on millions of machines and shipping a new release every two weeks.

If you're picking a testing tool today, you need both halves of the story. Get coffee. We're going to walk through what Cypress actually is, what makes it special, what it can't do, and where it sits in 2026.

What Cypress Actually Is (Architecturally, Which Is The Whole Story)

Most articles about Cypress start with "it's an end-to-end testing framework" and move on. That sentence is correct and useless. The thing you have to understand about Cypress the thing that explains every strength and every weakness, every pleasant surprise and every infuriating limitation is where the test code runs.

In Selenium, in Playwright, in basically every other browser-based testing tool, your test code runs in a Node.js process, outside the browser. The test process talks to the browser through a protocol WebDriver in Selenium's case, Chrome DevTools Protocol in Playwright's. When you write await page.click('button'), that's a Node-side instruction that travels over a wire, gets executed inside the browser, and reports back.

Cypress doesn't do this. Cypress runs your test code inside the browser, in the same JavaScript event loop as the application under test. There's a Node.js process that handles file watching, network proxying, and CI orchestration. But the actual cy.get('.button').click() you wrote runs in an iframe that's a sibling of your app, in the same tab, with full direct access to the DOM, the window object, and every JavaScript runtime detail.

This decision is the single most important thing about Cypress. It's why Cypress feels magical when it works and frustrating when it doesn't.

Because the test code lives in the browser, Cypress can do things other tools can't easily do. It can synchronously inspect any DOM node. It can stub window.fetch at the source. It can take a complete snapshot of the DOM after every command and let you scrub through them like a video. It can show you the application running while the tests run, with a sidebar of commands you can click to see exactly what the page looked like at that moment. The "time-travel debugger" everyone raves about isn't a feature so much as a free side effect of where the code lives.

But the same architectural choice forecloses certain things permanently. Browsers are designed so that code in one tab cannot control another tab. So Cypress, by definition, cannot test multi-tab flows there's no second tab for it to reach into. The same-origin policy, which is fundamental to web security, means Cypress can't navigate to a different origin and keep running, because that would be a sandbox violation. (They've worked around this with cy.origin(), but the workaround has its own limits.) Real Safari support is hard, because Safari's WebKit doesn't expose the same hooks Chromium does for in-browser test injection. Parallelism is hard, because each browser instance needs its own coordinator and the natural parallelism of a Node process spawning workers doesn't apply.

If you keep this architectural difference in mind, every Cypress strength and every Cypress limitation makes immediate sense. It's not arbitrary product design. It's the consequence of a single decision made in 2014 and lived with ever since.

How Cypress Got Big

Brian Mann started Cypress around 2014 because he was tired of writing brittle Selenium tests for his own team. The first commit landed on June 5, 2014. Public beta was October 2017. Commercial launch came in October 2018. By 2019, every JavaScript developer I knew had at least heard of it, and most had tried it.

The reason it caught on was not architectural cleverness most users didn't and don't care how it works inside. The reason was that writing the first test was joyful. You ran cypress open and the runner showed you your app and the test side by side. You could see the test run. You could click any command in the log to time-travel. When something failed, the runner showed you exactly which element wasn't found, with a screenshot of the page at the moment of failure. There were no Selenium grids to set up, no Chromedriver versions to manage, no flakiness from "stale element reference" errors. Tests just worked, mostly, and when they didn't, you could see why.

Compared to Selenium which had been the only serious option for ten years this was a revelation. Compared to the other test frameworks that existed at the time (Nightwatch, WebdriverIO, TestCafe), Cypress just felt nicer. The docs were good. The error messages were good. The DX was, frankly, an order of magnitude better than what came before.

By 2021, Cypress had been adopted by Slack, Disney, the NBA, Netflix, Shopify, LEGO, NASA, GitHub, Vercel, and Netlify (their own marketing materials, which is to say: don't quote this as a current state of affairs, since several of those teams have publicly or quietly migrated since). The company had raised $54M across a 2019 Series A and a 2020 Series B. They launched Cypress Dashboard (later renamed Cypress Cloud) as the paid product. Things were, by every metric, going great.

Then Microsoft launched Playwright in 2020.

The Anatomy of a Cypress Test

Before we get to the comparison, let's talk about what writing Cypress tests actually feels like, because this is the part that people either fall in love with or get frustrated by within twenty minutes.

A typical Cypress test looks like this:

describe('login flow', () => {
  beforeEach(() => {
    cy.visit('/login')
  })

  it('logs in with valid credentials', () => {
    cy.get('[data-cy=email]').type('jane@example.com')
    cy.get('[data-cy=password]').type('correct-password')
    cy.get('[data-cy=submit]').click()
    cy.url().should('include', '/dashboard')
    cy.contains('Welcome back, Jane').should('be.visible')
  })
})

There are several things going on here that look like JavaScript but aren't.

cy.get is not a function call that returns an element. It's a command that gets queued. When you write cy.get('[data-cy=email]').type('jane@example.com'), you are not actually getting the email field and then typing into it. You are appending two commands to a queue. After your it block returns, Cypress walks the queue and executes the commands one at a time, with each command's result feeding into the next.

This is the part that breaks people's brains, so let me say it again with feeling. Cypress commands are not promises. Cypress commands cannot be awaited. The official docs say so explicitly: "While the API may look similar to Promises, with its then() syntax, Cypress commands and queries are not promises they are serial commands passed into a central queue, to be executed asynchronously at a later date."

This means the following code, which you will absolutely write at some point, does not work:

// DOES NOT WORK
const text = await cy.get('.title')
console.log(text)  // undefined

The await succeeds sort of but text is not the element. It's whatever Cypress decides to return, which is not what you want. The correct version is:

cy.get('.title').then($el => {
  const text = $el.text()
  // do something with text inside this callback
})

You have to do everything inside the chain. You can't extract a value, do some plain JavaScript with it, and then resume Cypress commands as if they were normal async/await code. The chain is the whole world.

The first time this hits you, it feels like a bug. The second time, it feels like an inconvenience. The hundredth time, after you've worked around it with custom commands and aliases and cy.then callbacks for two years, it feels like the cost of admission. Some developers love it, because the queue-based model is what enables the magic of automatic waiting and time-travel debugging. Some developers hate it, because it forecloses entire categories of normal JavaScript patterns.

GitHub issue #1417, "Await-ing Cypress Chains," is one of the most-engaged issues in the project's history. The answer, which has been the answer since 2017, is still no. Cypress's whole architecture would have to change.

The Best Thing Cypress Got Right: Implicit Assertions and Auto-Waiting

Here's the thing Cypress nailed and nobody else had really cracked at the time. Look at this:

cy.get('.notification').should('contain', 'Saved')

This command does something subtle. It tries to find .notification. If it doesn't exist yet, it retries. If it exists but doesn't contain "Saved" yet, it retries. If both conditions become true within the timeout (default four seconds), the command passes. If neither is true after four seconds, it fails.

You don't write await page.waitForSelector followed by a separate assertion. The assertion is the wait. The wait is the assertion. They're the same thing.

This was the answer to the most common form of test flakiness. In Selenium tests, you'd write something like:

await driver.wait(until.elementLocated(By.css('.notification')), 5000)
const text = await driver.findElement(By.css('.notification')).getText()
expect(text).to.contain('Saved')

Three operations, three opportunities for a race condition. You wait for the element to be located, then you find it (it might have re-rendered between those steps), then you get its text (it might have changed). Cypress collapses all of this into one retry-able assertion. The element either exists and contains the text within four seconds, or it doesn't. If your test is going to be flaky here, it'll be flaky on this one line, not on three different lines for three different reasons.

This pattern alone is responsible for a lot of Cypress's reputation for "non-flaky" tests. It's not that the tool magically eliminated race conditions. It's that the API made the right thing easy to write.

Playwright eventually adopted similar patterns expect(locator).toContainText(...) retries the way Cypress's should does but Cypress had it first, and for a few years that mattered.

cy.intercept: Network Stubbing That Doesn't Suck

Cypress 6.0, released in December 2020, introduced cy.intercept. Before it, network stubbing was done with cy.route and cy.server, which only worked for XHR meaning if your app used fetch (which by 2020 most apps did), you were out of luck without a workaround.

cy.intercept works at the proxy layer. It catches every network request the page makes, regardless of whether it's XMLHttpRequest, fetch, an iframe load, a WebSocket handshake, or a static asset. You can spy on requests, stub them with static responses, or attach handlers that modify requests and responses on the fly:

// Spy mode wait for the request, don't change it
cy.intercept('GET', '/api/users').as('getUsers')
cy.visit('/users')
cy.wait('@getUsers')

// Static stub
cy.intercept('GET', '/api/users', { fixture: 'users.json' })

// Dynamic handler
cy.intercept('POST', '/api/login', (req) => {
  if (req.body.password === 'correct') {
    req.reply({ statusCode: 200, body: { token: 'abc123' } })
  } else {
    req.reply({ statusCode: 401, body: { error: 'Invalid credentials' } })
  }
})

The cy.wait('@alias') pattern is the real magic. Instead of cy.wait(2000), you wait until a specific network request happens. Tests get faster (you only wait as long as you need to) and less flaky (you're not guessing how long the network will take). The Cypress best practices page is dogmatic about this, and it's right. Every time I see cy.wait(5000) in a codebase, I know I'm about to find a flaky test.

cy.intercept is, hands down, my favorite Cypress feature. It's the part of the API that has aged the best, and it's still genuinely competitive with Playwright's page.route (which works similarly but with slightly different ergonomics).

The Famous Errors

You can't write about Cypress without writing about its errors, because every Cypress developer alive has seen these specific messages and felt the specific kind of dread they produce.

"This element is detached from the DOM." Here's the actual text:

CypressError: Timed out retrying after 4050ms: cy.click() failed because this element is detached from the DOM. Cypress requires elements be attached in the DOM to interact with them. The previous command that ran was: > cy.should() This DOM element likely became detached somewhere between the previous and current command. Common situations why this happens: - Your JS framework re-rendered asynchronously - Your app code reacted to an event firing and removed the element

What this means: Cypress found the element, was about to click it, and in the millisecond between finding and clicking, your React component re-rendered and replaced the DOM node with a new one. The reference Cypress has is now pointing to a node that no longer exists in the document.

The fix is usually to re-query break the chain so Cypress refetches the element right before the click. Cypress 12 in December 2022 made this much better by rewriting the query commands to retry-and-re-query automatically in many cases. It still happens, especially with libraries like react-select or Material UI's autocompletes that do aggressive async re-rendering. GitHub issues #5743, #6215, #7306, #17043, #25863 are all this same problem with collectively thousands of upvotes.

"Cypress detected a cross origin error." Exact text:

CypressError: Cypress detected a cross origin error happened on page load: Blocked a frame with origin "http://example.com" from accessing a cross-origin frame.

Before Cypress 9.6 in April 2022, this was a near-fatal limitation. If your test needed to navigate to a different origin say, an OAuth provider you basically couldn't. The workaround was chromeWebSecurity: false, which disabled most of the browser's security model for the test run, and even that didn't always work.

cy.origin('https://other.example.com', () => { ... }) is the modern fix. It runs the callback in the context of the other origin. It works, but with caveats. You can't nest origins. The callback runs in a fresh JavaScript context, so closures over outer-scope variables don't work you have to explicitly pass them in via the args option. And the syntax is, frankly, awkward enough that I've seen teams just write OAuth flows as API requests in cy.request() instead, bypassing the UI entirely.

"Cannot click on multiple elements." Cypress, by design, refuses to operate on multiple matching elements unless you explicitly ask for them. This is good philosophy your test should know exactly which element it's targeting but it produces this error any time your selector matches more than one thing, and figuring out which extra element matched can take longer than you'd think.

The chain is broken errors when you accidentally try to use a Cypress command outside the chain context, or you await something you shouldn't have, the error messages are detailed but not always actionable. New users hit these constantly.

cy.session: The Quiet Revolution

If you've been writing Cypress tests for years and still log in via the UI in beforeEach, please stop. cy.session() exists. It's been GA since Cypress 12 in December 2022. With cacheAcrossSpecs: true, you log in once per test run instead of once per test:

const login = (email) => {
  cy.session(
    email,
    () => {
      cy.visit('/login')
      cy.get('[data-cy=email]').type(email)
      cy.get('[data-cy=password]').type(Cypress.env('PASSWORD'))
      cy.get('[data-cy=submit]').click()
      cy.url().should('include', '/dashboard')
    },
    { cacheAcrossSpecs: true }
  )
}

beforeEach(() => {
  login('jane@example.com')
  cy.visit('/some-page')
})

The first time login('jane@example.com') runs, it executes the callback. Cypress captures all the cookies, localStorage, and sessionStorage at the end. Every subsequent call with the same key restores those cookies and storage instead of running the callback again. On a 100-test suite where logging in takes two seconds, this saves more than three minutes per run.

Filip Hric's blog post "Use cy.session instead of login page object" is the canonical write-up if you want to dig deeper. The pattern took a while to spread because it was experimental for so long, but in 2026 there's no excuse for not using it.

Component Testing in Cypress

Cypress 10, released June 1, 2022, made Component Testing a first-class mode. You can mount React, Vue, Angular, or Svelte components directly in the runner and test them in isolation:

import Stepper from './Stepper'

describe('<Stepper />', () => {
  it('increments and decrements', () => {
    cy.mount(<Stepper initialValue={0} />)
    cy.get('[data-cy=increment]').click()
    cy.contains('1').should('be.visible')
    cy.get('[data-cy=decrement]').click()
    cy.contains('0').should('be.visible')
  })
})

The pitch is real: you're testing in a real browser, with real CSS, real layout, real DOM. JSDOM (which React Testing Library uses by default) lies about a lot of layout-related things. Visibility checks are unreliable. Hover states don't work. CSS that depends on the viewport doesn't render correctly. Cypress component tests don't have those problems.

So why hasn't it taken over? Two reasons.

First, RTL plus Vitest is faster. A lot faster. Cypress component tests need to boot a browser, load a dev server, and render the component, all per spec file. Vitest tests run in milliseconds and parallelize across CPU cores trivially. For most components buttons, forms, data displays JSDOM is fine, and the speed difference matters more than the fidelity difference.

Second, the React testing ecosystem standardized on RTL in 2020, and that gravity is hard to escape. Most teams have RTL tests already. Most tutorials use RTL. The "Testing Library" mental model (test what the user sees, not implementation details) is what every senior React developer absorbed.

Cypress component testing is genuinely useful for visual-heavy components, complex hover/focus interactions, drag-and-drop, anything where the real DOM matters. For most teams it ends up being a complement to RTL, not a replacement.

Cypress Cloud and the Cost Question

The free Cypress runner is MIT-licensed and complete. You can run thousands of tests on your laptop or in CI without paying anyone. Where Cypress.io makes its money is Cypress Cloud, which records test runs to a dashboard, provides screenshots and videos, and crucially handles parallelization.

Here's the part that drives migrations. Parallelization is paywalled. If you want to split your test suite across multiple CI machines to make it run faster, you need a Cloud subscription. The free tier gives you 500 test results per month, which a real CI pipeline can chew through in a day or two.

Pricing as of early 2026 looks roughly like:

Free / Starter: 500 results/month, 3 users, 30-day retention
Team: around $67/month
Business: around $267/month
Enterprise: custom, typically $15K to $40K+ annually for mid-market

For a one-developer side project, free is fine. For a five-person team, Team works. For a real product with a proper CI pipeline, you're either paying low four figures a year for Business or you're rolling your own parallelization with cypress-split or Sorry Cypress or Currents.dev.

This pricing model free OSS tool, paid coordination layer is the same model GitLab and HashiCorp use, and it's defensible. But for testing tools, where Playwright offers parallelization for free, it stings. The BigBinary blog post "Why we switched from Cypress to Playwright" cites paywalled parallelization as one of their two main migration triggers, alongside the inability to bypass third-party bot detection in real OAuth flows.

Cypress Cloud has shipped genuinely impressive new features in the last two years Test Replay (think Playwright's Trace Viewer but for CI runs), UI Coverage (visualizes what percent of your UI is exercised by tests), Cypress Accessibility (axe-core scans on every recorded run), and recently Cloud MCP for AI assistants. These are real and they solve real problems. But they're also enterprise features at enterprise prices, and the message they send is clear: Cypress.io's commercial focus has moved upmarket.

The Playwright Comparison We've Been Avoiding

Let's just do this.

In June 2024, Playwright passed Cypress in weekly npm downloads for the first time. Since then the gap has only widened. As of late April 2026, Playwright sits around 48 million weekly downloads to Cypress's 7 million. State of JS 2024 showed Playwright leading on retention (the percentage of users who say they'd use it again) at around 94%, with Cypress around 74%. Playwright's GitHub stars are roughly 86,000 to Cypress's 49,600.

These numbers are not close.

The reasons, in approximate order of how often I hear them cited by teams that migrated:

Free parallelization. Playwright parallelizes across CPU cores by default. No paid cloud needed. For teams that were paying mid-four-figures a year for Cypress Cloud just to get tests running fast in CI, this alone justifies the migration.

Multi-browser, including real WebKit. Playwright runs against Chromium, Firefox, and WebKit (which is Safari's engine). Cypress can run against Chrome, Edge, Firefox, and Electron, but not WebKit. If your users use Safari and on iOS, your users always use Safari Playwright actually tests their browser. Cypress doesn't.

Multi-tab, multi-origin, multi-context. Cypress can't open a second tab. Playwright can, trivially. Cypress's cy.origin works but has limitations. Playwright treats different origins as a non-event.

Real async/await. Playwright tests are normal async JavaScript. You can await anything. You can mix Playwright calls with regular function calls and Promises without thinking about it. The mental model is just JavaScript. Coming from Cypress, this feels like a weight lifting.

Speed. The BigBinary writeup cites their auth flow going from two minutes in Cypress to under twenty seconds in Playwright. One of their isolated tests went from 16 seconds to 1.8 an 88% speedup. Playwright's out-of-process design makes parallelism easy, and it's just generally faster at routine operations.

Trace Viewer. Playwright's equivalent of Cypress's time-travel debugger is Trace Viewer, and it's good. You get DOM snapshots, network logs, console logs, action timelines, all for every test run, all without paying anyone.

These are real advantages and they're not subjective. If you're greenfielding a project in 2026 and you don't have a strong reason to pick Cypress, you should probably pick Playwright. I say this as someone with eight hundred Cypress tests in production and tattoos that say "data-cy" on them figuratively.

So why am I writing this article instead of an article called "Don't Use Cypress"? Because Cypress still has things going for it.

The runner experience the live, interactive GUI where you watch your tests run alongside your application is still better than Playwright's UI mode in some ways, especially for debugging and authoring new tests. The time-travel debugger is still uniquely good. The community knowledge base the Stack Overflow answers, the recipe blogs, the years of accumulated patterns is enormous, even compared to Playwright. Component testing in a real browser is a genuine niche that Playwright doesn't really compete in. And for teams that already have a thousand Cypress tests in production, the migration cost is non-trivial. We did the math at one point: at our pace, migrating our suite would have taken about four engineering months. That's a lot of months.

If you're starting fresh: Playwright. If you're considering migrating: do the math. If you're staying on Cypress: that's a perfectly defensible choice in 2026, you just need to know what you're trading off.

Best Practices That Actually Matter

If you're going to write Cypress tests, the official best practices page is genuinely worth reading top to bottom. The greatest hits, with my commentary:

Use data-cy (or data-test) attributes for selectors. Not classes. Not IDs. Classes change for styling reasons. IDs sometimes change for accessibility reasons. data-cy exists for one reason to be a stable selector for tests and that's its whole job. The Cypress Selector Playground autodetects them.

Don't write conditional tests. If you find yourself writing if (element exists) { do thing } else { do other thing }, your test isn't deterministic. Either the thing is going to happen or it isn't. Pick one and assert on it.

Don't share state between tests. Each test should set up everything it needs. Use cy.session for auth, cy.task to seed your database, cy.intercept to control the network. Don't rely on test A having logged in before test B runs.

Don't use cy.wait(milliseconds). Ever. This is the single biggest cause of slow, flaky Cypress tests in the wild. Wait on aliases (cy.wait('@apiCall')) or wait on assertions (cy.get('.thing').should('be.visible')). Cypress's whole retry-ability machinery is designed to make cy.wait(5000) unnecessary. If you're using it, you're fighting the framework.

Always start a new chain after an action. Don't try to chain queries through a .click(). Click ends a chain. Start fresh:

// Sketchy
cy.get('.btn').click().get('.result')

// Better
cy.get('.btn').click()
cy.get('.result')

Don't test multiple flows in one test. A test should do one thing. If you find yourself writing it('handles signup, login, and password reset'), split it. Cypress is fast enough that the overhead per test is minimal compared to the debugging cost when one big test fails for unclear reasons.

Don't use traditional Page Object Models. This one is contentious. Cypress's official guidance is to skip the POM pattern and use custom commands plus data-cy attributes instead. The community is split there are a thousand Cypress POM tutorials online but I've come around to Cypress's view. POMs add a layer of abstraction that doesn't pay off in a queue-based command model. Custom commands give you the same encapsulation with less ceremony.

Use Cypress.Commands.add for repeated patterns. A cy.login(email) command, once written, makes every subsequent test cleaner. Same for any UI flow that repeats opening a dialog, filling a form, navigating to a tab.

What's Still Hard

Honesty corner. There are things Cypress is just bad at, even in 2026:

iframes. They're better than they used to be, but still awkward. The cypress-iframe plugin helps. Tests that involve embedded payment forms (Stripe Elements, etc.) are usually either painful or written as API tests instead.

File downloads. Cypress has no built-in way to verify a file was downloaded. You either intercept the download URL and check the response, or you use a plugin like cypress-downloadfile, or you skip it.

Mobile emulation. You can set a viewport size, but real mobile emulation touch events, mobile-specific network conditions, device frames is limited. Playwright is significantly better here.

Visual regression testing. Cypress doesn't have built-in visual diffing. You bolt on Percy, Applitools, or Cypress Cloud's own UI Coverage feature. Each costs money. Playwright has built-in screenshot comparison.

WebKit/Safari. Just no. Not happening. The architecture forecloses it.

Performance testing. Cypress is for functional testing. If you want Lighthouse-style metrics or detailed performance traces, you're in Playwright territory.

The async chain still trips up new developers. I've onboarded probably a dozen engineers onto Cypress over the years, and every single one hit the "why doesn't await cy.get() work" wall in their first week. It's a well-trodden path with good explanations available, but it's still a path.

When to Pick Cypress in 2026

After all that, here's my honest recommendation framework.

Pick Cypress if: you primarily test in Chromium, you value a live interactive runner above all else, your team is small enough that the free tier or Team tier is enough, you don't need multi-tab or multi-origin in serious ways, your existing team already knows Cypress, you have an existing Cypress test suite that's working, or you genuinely prefer the queue/chain mental model after trying both.

Pick Playwright if: you need cross-browser including WebKit, you have a complex CI parallelization need, you need multi-tab or multi-context flows, you're starting fresh in 2026 with no existing tests and no team preference, you want async/await to just work, or your application includes serious mobile flows.

Pick neither if: you're testing a static site or a simple form, in which case Cypress and Playwright are both overkill and you should just write a few integration tests with Vitest plus jsdom and call it a day.

For component testing specifically, default to React Testing Library plus Vitest, and reach for Cypress component testing only when you have specific real-browser needs.

A Realistic Cypress Test File in 2026

Here's what I think a healthy Cypress E2E test file looks like today:

describe('Checkout Flow', () => {
  beforeEach(() => {
    cy.session('checkout-user', () => {
      cy.request('POST', '/api/test/login', {
        email: 'test@example.com',
        password: Cypress.env('TEST_PASSWORD'),
      }).then(response => {
        window.localStorage.setItem('token', response.body.token)
      })
    }, { cacheAcrossSpecs: true })

    cy.intercept('GET', '/api/products*').as('getProducts')
    cy.intercept('POST', '/api/orders').as('createOrder')

    cy.visit('/shop')
    cy.wait('@getProducts')
  })

  it('completes checkout with valid card', () => {
    cy.get('[data-cy=product-card]').first().within(() => {
      cy.get('[data-cy=add-to-cart]').click()
    })

    cy.get('[data-cy=cart-button]').click()
    cy.get('[data-cy=checkout-button]').click()

    cy.get('[data-cy=card-number]').type('4242424242424242')
    cy.get('[data-cy=card-expiry]').type('1234')
    cy.get('[data-cy=card-cvc]').type('123')

    cy.get('[data-cy=pay-button]').click()

    cy.wait('@createOrder').its('response.statusCode').should('eq', 201)
    cy.url().should('include', '/order-confirmation')
    cy.contains(/thank you/i).should('be.visible')
  })

  it('shows error on declined card', () => {
    cy.intercept('POST', '/api/orders', {
      statusCode: 402,
      body: { error: 'Card declined' }
    }).as('declinedOrder')

    cy.get('[data-cy=product-card]').first().within(() => {
      cy.get('[data-cy=add-to-cart]').click()
    })
    cy.get('[data-cy=cart-button]').click()
    cy.get('[data-cy=checkout-button]').click()
    cy.get('[data-cy=card-number]').type('4000000000000002')
    cy.get('[data-cy=card-expiry]').type('1234')
    cy.get('[data-cy=card-cvc]').type('123')
    cy.get('[data-cy=pay-button]').click()

    cy.wait('@declinedOrder')
    cy.contains(/card declined/i).should('be.visible')
    cy.url().should('not.include', '/order-confirmation')
  })
})

Notice the patterns. Authentication via cy.session with cross-spec caching. Network calls aliased and waited on by alias, never by milliseconds. Selectors all use data-cy. Each test does one thing. Setup happens via the API where possible (the login bypasses the UI entirely with cy.request), reserving the UI exercise for the actual feature being tested. Stubbed responses for failure scenarios using cy.intercept's static stub mode. Assertions are should-based, leveraging implicit retry-ability.

If your Cypress tests look something like this, you're in good shape. If they look like a hundred lines of cy.wait(2000) and UI-based logins in beforeEach, you have an afternoon's worth of cleanup that will make your suite dramatically faster and less flaky.

The Closing Argument

Cypress was the first testing tool that made me enjoy writing browser tests. That's not a small thing. For ten years before Cypress, browser testing was a chore that everyone did badly because the tools were bad. Cypress changed the baseline expectation for what these tools should feel like. Every modern alternative, including Playwright, has been pulled forward by Cypress's example.

That doesn't mean it's the right tool for new projects today. The architectural choices that made Cypress feel magical in 2017 running in the browser, queue-based commands, time-travel by default are also the choices that have foreclosed multi-browser and multi-tab and easy parallelism, and the world has moved toward those things mattering more.

If I'm starting a new project tomorrow, I'm starting with Playwright. If I'm advising a team with an existing Cypress suite that's working, I'm telling them to keep it and use the time saved to ship features. If I'm hiring, I'm looking for people who understand testing principles, not specific tools, because both will be relevant for years to come.

The good news is that the principles are the same regardless. Test what the user does, not what the code does internally. Wait on conditions, not on time. Set up state programmatically, exercise the UI for the thing under test, assert on what's visible. Don't share state. Don't get clever. Whether you write that with cy.get or page.locator, the test that comes out the other side will be the same kind of test. The tool is a syntax. The thinking is the work.

Now if you'll excuse me, I have eight hundred tests to keep alive.

5 Things AI Can't Do, Even in React Testing Library

DevUnionX — Tue, 28 Apr 2026 02:02:29 +0000

I Spent Three Years Writing the Wrong React Tests. Here's What I Wish Someone Had Told Me.

If you wonder my game:

Electricity Tycoon - Apps on Google Play

Build your electricity empire from a hand crank to industrial power plants.

play.google.com

The first React test I ever wrote checked that a component's state had a property called count and that it equaled zero. I was using Enzyme. I was very proud. The test passed. Six weeks later we refactored that component to use a reducer and renamed count to value, and seventeen tests in the same file went red even though the application worked exactly the same as before. I spent a Friday afternoon updating tests that tested nothing useful.

If you've been writing React tests for any length of time, you've probably had this experience. The tests pass. The tests fail. The tests don't seem to care whether your application actually works for an actual human being. You start to wonder if testing is just an elaborate ceremony we perform to feel professional.

It isn't. But the tools we used to use made it feel that way, and the tools we use now — primarily React Testing Library — have a philosophy that makes everything click into place once you internalize it. This article is the long version of "internalize it." Get coffee. We're going to talk about queries, async, the act() warning that has eaten more developer hours than any other single warning in frontend history, why your snapshots are lying to you, and what the actual state of React testing looks like in April 2026.

The Sentence That Changed React Testing

There is one sentence on the testing-library.com docs that you should tattoo on the inside of your eyelids:

The more your tests resemble the way your software is used, the more confidence they can give you.

That's it. That's the whole framework. Everything that follows in this article — every query priority, every async pattern, every reason to delete your snapshot tests — is a consequence of that one sentence.

Kent C. Dodds wrote it in a tweet years ago, then it became the project tagline, then it became the README of every Testing Library repo, and now it's basically the unofficial constitution of the React testing world. The reason it matters is that it tells you what to optimize for. You're not optimizing for code coverage. You're not optimizing for "every function has a test." You're optimizing for confidence that your application works for the people who use it.

Most of the bad testing habits I had with Enzyme came from optimizing for the wrong thing. I was optimizing for "every component has a corresponding test file with the same name." I was optimizing for "every line of code is covered." I was optimizing for the dashboard at the top of our CI tool. None of those things told me whether the user could actually click the button and have something happen.

Why Enzyme Died (And Why That Was a Good Thing)

Enzyme is dead. I should say this with some kindness because Enzyme was important and a lot of us learned testing on it, but it's been clinically dead since December 21, 2019, when version 3.11.0 shipped and then nothing happened for the next six and a half years. There is no official React 17 adapter, no React 18 adapter, no React 19 adapter. Community-maintained adapters exist — @wojtekmaj/enzyme-adapter-react-17 and @cfaester/enzyme-adapter-react-18 — but the maintainer of one of them literally writes "you probably shouldn't use it" in the README. That's the state of things.

The reason Enzyme died is interesting. It wasn't a security issue. It wasn't that React broke it on purpose. It was that the React team moved toward concurrent rendering and hooks, and Enzyme's whole API was built around the idea that you could reach into a component and inspect its instance — its state, its props, its internal methods. With hooks, there's no instance to inspect. There's just a function that runs. Enzyme's mental model didn't have a place for that.

But the deeper reason Enzyme died is that the way it encouraged you to write tests was structurally wrong. You'd render a component, then assert on its state. You'd call wrapper.instance().handleClick() directly. You'd use shallow() rendering, which renders only one component without its children, and then you'd assert that a child component received certain props. None of these things are things a user does. A user doesn't know your component has state. A user doesn't call your handler functions directly. A user doesn't know what's a parent and what's a child.

Kent C. Dodds wrote a post called "Testing Implementation Details" that still gets quoted constantly. The line that landed for me was about renaming. Imagine your component has a state variable called openIndex. You can rename it to openIndexes, or to tacosAreTasty, and the application works exactly the same. The user can't tell. The interface to the outside world hasn't changed. But every test that asserted on openIndex just broke. That's a false negative. The test failed but nothing is broken.

The opposite happens too. You can break the application — say, the click handler stops actually doing anything — and your test still passes because it was checking that state.count got incremented, not that anything appeared on the screen. That's a false positive. The test passed but everything is broken.

When most of your test failures fall into one of those two categories, you stop trusting your tests. And once you stop trusting your tests, you might as well not have them.

The Query Priority Hierarchy (And Why It Exists)

React Testing Library gives you a bunch of ways to find elements in the DOM. They're not equivalent. They're ranked, and the ranking is opinionated, and the opinion comes from that one sentence about resembling how users use your software.

Here's the order, with my unsolicited commentary on each.

getByRole is the one you should reach for first. Almost always. If you're writing a test and you find yourself reaching for something else, ask whether you can use getByRole instead. It works for buttons, links, headings, form inputs (textbox, checkbox, radio, combobox), regions, dialogs, lists — basically every meaningful piece of a web interface. The reason it's at the top is that ARIA roles are how assistive technology like screen readers understands your page. If your test can find a button by its accessible role and name, then a screen reader user can find that button too. The query is also surprisingly tolerant. screen.getByRole('button', {name: /submit/i}) finds a button whose accessible name contains "submit", case-insensitive. You don't need exact text. You don't need an ID. You're describing the button the way a person would describe it.

getByLabelText is for form fields. When a sighted user fills out a form, they look at the label and then click the field next to it. When a screen reader user fills out a form, the label is announced when the field is focused. Either way, the label is the user's way in. So screen.getByLabelText(/email/i) is how your test should find the email field, not by some data-cy="email-input" attribute. The bonus is that if your test breaks because the label disappeared, that's actually a real bug — your form just became inaccessible.

getByPlaceholderText is a fallback for when a field has no label. The docs are clear about this: a placeholder is not a substitute for a label. But sometimes you're testing legacy code and there's just no label. Fine. Use it. Then file a ticket to add a label.

getByText is for non-interactive content. Headings, paragraphs, status messages, error text. If the user can read it on the page, your test can find it.

getByDisplayValue finds form elements by their current value. Useful when you're testing that a form is pre-populated with edit data.

getByAltText for images. getByTitle is rarely useful and the docs warn that title attributes aren't consistently announced by screen readers anyway.

And finally, at the bottom: getByTestId. This is the escape hatch. The docs literally say "the user cannot see (or hear) these, so this is only recommended for cases where you can't match by role or text or it doesn't make sense." If your codebase has data-testid sprinkled on every other element, that's a smell. It usually means somebody learned testing-library by Googling "how do I find an element in RTL" and the first Stack Overflow answer said getByTestId. There's a reason it's last on the list.

The mental shift takes a while. The first time I sat down to convert a test to use getByRole instead of container.querySelector('.submit-btn'), I had to actually look at my component and ask "wait, is this even a button? Or did I make a div with an onClick?" Half the time the answer was "I made a div with an onClick" and the test was forcing me to fix the accessibility of the component before I could even test it. That's the whole point.

getBy, queryBy, findBy — The Cheat Sheet Nobody Reads

There are three flavors of every query, and developers confuse them constantly. Here's what they do.

getBy* throws an error if the element isn't found, returns it if it is. Use this for "I'm asserting this element exists." If you do screen.getByRole('button', {name: /submit/i}) and there's no submit button, your test fails with a useful error message that includes the entire DOM and a list of all the roles that do exist. Helpful.

queryBy* returns null if the element isn't found, returns it if it is. Use this for "I'm asserting this element does NOT exist." Because if you used getByText('Error') to assert that no error was shown, the getBy would throw before your assertion ever ran. So you do expect(screen.queryByText('Error')).not.toBeInTheDocument() instead.

findBy* returns a Promise that resolves when the element appears, or rejects after a timeout (default 1000ms). Use this for "I'm asserting this element will appear, but not synchronously." Anything triggered by an async effect, a network request, a state update after a user event — findBy*. The docs put it plainly: findBy* is literally getBy* plus waitFor. Just shorter.

The number one mistake I see in code review is people using getByText to check for something that hasn't appeared yet, then wondering why the test fails. The element isn't there yet. Wait for it. Use findByText.

The number two mistake is using getByText to assert something is gone. Use queryByText. The error you get from getByText failing is "Unable to find an element with text," which is technically true but not what your test is trying to say.

There's also getAllBy*, queryAllBy*, and findAllBy* for when you expect multiple matches. The behavior is what you'd guess.

fireEvent vs user-event: The Day I Learned to Add `await`

For the first year I used React Testing Library, I used fireEvent for everything. fireEvent.click(button). fireEvent.change(input, {target: {value: 'hello'}}). It worked. Tests passed. Life was good.

Then I read the user-event docs and realized I'd been simulating the wrong thing.

fireEvent dispatches a single DOM event. Period. fireEvent.click(button) fires a click event. That's it. No focus event, no mousedown, no mouseup. Just click. fireEvent.change(input, {target: {value: 'hello'}}) fires a single change event with the value already set. The user never actually typed anything. The input was never focused. No keystrokes happened. From the DOM's perspective, the value just teleported in.

user-event simulates what actually happens when a real human interacts with the page. user.click(button) triggers a mousedown, then a mouseup, then a click, and along the way it focuses the button if it's focusable. user.type(input, 'hello') focuses the input, then for each character fires a keydown, a keypress, an input event, and a keyup. It manipulates the cursor position. It does what a real keyboard does.

This matters more than you'd think. There are bugs that only appear when events fire in a specific order. There are form libraries (looking at you, react-hook-form) that depend on focus and blur events to run validation. There are accessibility behaviors that hinge on whether an element actually got focused. If you use fireEvent, none of this gets exercised. Your test runs in a fantasy world where state just changes.

In version 14 of user-event (released March 2022, currently at 14.6.1 as of January 2025), every interaction became asynchronous. This was a big migration pain at the time and is still tripping people up in 2026 because half the tutorials online are from before the change. The new pattern looks like this:

import userEvent from '@testing-library/user-event'

test('submits the form', async () => {
  const user = userEvent.setup()
  render(<MyForm />)

  await user.type(screen.getByLabelText(/email/i), 'jane@example.com')
  await user.click(screen.getByRole('button', {name: /submit/i}))

  expect(await screen.findByText(/thanks/i)).toBeInTheDocument()
})

Notice three things: userEvent.setup() is called once at the top, every interaction is awaited, and we use findByText for content that appears after async work.

The number one symptom of forgetting an await somewhere is the warning we're about to talk about.

The act() Warning: A Eulogy In Three Acts

If you've written React tests and never seen the act() warning, you have not actually written React tests. Here it is, in its full glory:

Warning: An update to ComponentName inside a test was not wrapped in act(...).

When testing, code that causes React state updates should be wrapped into act(...):

act(() => {
  /* fire events that update state */
});
/* assert on the output */

This ensures that you're testing the behavior the user would see in the browser.

I have seen this warning in production codebases. I have seen it in tutorials. I have seen it in pull request descriptions where the author says "ignore the warnings, the tests pass." I have personally spent multiple full evenings hunting down a single act warning in a single test file. It is the most universally hated message in the React ecosystem and it is also, somewhat unfairly, almost always your fault.

Here is what act() actually is. React batches state updates and side effects in production. When you're testing, you want to make assertions on the DOM after all those batched updates have flushed. act() is the mechanism that says "do all the React work, including effects, before this function returns." If you cause a state update without it being inside an act() boundary, React doesn't know whether you're going to do more updates next, so it warns you that the test environment isn't behaving like the browser.

The good news is that React Testing Library wraps almost everything in act() for you. render() is wrapped. fireEvent is wrapped. waitFor is wrapped. findBy* is wrapped. user-event v14 is wrapped. You almost never need to call act() yourself.

So why do you keep seeing the warning?

Because something is updating state after your test thinks it's done. The most common cause is a useEffect that runs after initial render and triggers a state update. Your test renders the component, makes its assertions, and exits — and then the effect fires, and React tries to update state, and there's no test left to be inside an act() boundary.

The fix is almost always to wait for the state to settle before your test ends. If you have a component that fetches data on mount, your test should look like:

test('shows the user list', async () => {
  render(<UserList />)
  expect(await screen.findByText(/jane doe/i)).toBeInTheDocument()
})

Notice the await on findByText. That's the magic. The test now waits until the data has loaded and the component has settled before it finishes. No more act warning.

If your effect updates state but doesn't render anything new (say, it sets some internal flag), use waitFor:

await waitFor(() => expect(mockSomething).toHaveBeenCalled())

If you're using fake timers, that's a whole separate can of worms. jest.useFakeTimers() runs code outside React's normal callstack, so the auto-act doesn't catch it. You need to manually wrap the timer advancement:

await act(async () => {
  jest.runAllTimers()
})

If you're using a form library like react-hook-form with async validation, you'll see the warning when validation runs after submit. The fix is to await something that depends on the validation completing — like an error message appearing, or a submit handler being called.

The thing not to do is wrap things that are already wrapped. I see this all the time:

// Don't do this — render is already wrapped in act
act(() => {
  render(<MyComponent />)
})

You're double-wrapping. It doesn't break anything but it produces a different warning telling you about overlapping act() calls. Stop.

One more thing. In React 19 (which RTL 16.1.0 added support for, on December 5, 2024 — the same day React 19 went GA), act is officially expected to be async. The synchronous version is deprecated. You should now import act from @testing-library/react, not from react. RTL has been re-exporting it since version 15.0.6 (May 2024). If you have old test files that import act from React, fix them.

Async Testing: findBy, waitFor, and the Order of Operations

Async testing in RTL has three primitives. You only really need to know two of them well, and the third is for edge cases.

findBy* is for waiting for an element to appear. Use this 80% of the time you need to wait for something. The default timeout is 1000ms, which is usually fine. If you need longer, you can override it: screen.findByText(/loaded/i, {}, {timeout: 5000}). Avoid bumping the timeout in normal cases — it usually means your component is doing something genuinely slow that you should fix.

waitFor is for waiting for an arbitrary assertion to pass. Use this when what you're waiting for isn't an element appearing — like waiting for a mock function to have been called, or waiting for a fetch to have happened.

// ✅ Good
await waitFor(() => expect(mockOnSubmit).toHaveBeenCalledWith({email: 'a@b.com'}))

// ❌ Bad — putting side effects inside waitFor
await waitFor(() => {
  user.click(button)
  expect(mockOnSubmit).toHaveBeenCalled()
})

The reason the second one is bad is that waitFor runs its callback repeatedly until either the assertion passes or the timeout fires. If you have a click event inside there, you'll fire that click event many times. That's not what you want.

waitForElementToBeRemoved is for waiting for something to disappear. Loading spinners, mostly. The pattern is:

await waitForElementToBeRemoved(() => screen.queryByText(/loading/i))

Notice we use queryByText here, not getByText. That's because at the moment the element is finally removed, getByText would throw (the element isn't there anymore), which would defeat the whole purpose.

The most common async testing mistake I've seen recently is using waitFor to look for an element when findBy would do:

// ❌ Verbose
const button = await waitFor(() => screen.getByRole('button'))

// ✅ Direct
const button = await screen.findByRole('button')

These are functionally equivalent. findBy* uses waitFor internally. The second version is shorter, the error messages are better, and it makes intent clearer.

Mock Service Worker, or, Stop Mocking fetch

If you're testing components that fetch data, you have a few options. Most of them are bad.

You can mock window.fetch with jest.fn(). This works but it's brittle — every test has to set up the mock, you couple your tests to the exact shape of the request, and as soon as you switch from fetch to axios to ky to whatever's trendy this week, all your tests break.

You can mock the network library directly. Same problem.

You can use Mock Service Worker (MSW). This is what the testing-library docs themselves recommend. MSW intercepts requests at the network level — it doesn't care whether you used fetch, axios, XMLHttpRequest, or carrier pigeons. You declare what your endpoints return, MSW handles the rest, and your component code is completely unchanged.

The MSW v2 API looks like this:

import { http, HttpResponse } from 'msw'
import { setupServer } from 'msw/node'

const server = setupServer(
  http.get('/api/users', () =>
    HttpResponse.json([{id: 1, name: 'Jane Doe'}])
  )
)

beforeAll(() => server.listen())
afterEach(() => server.resetHandlers())
afterAll(() => server.close())

test('shows the user list', async () => {
  render(<UserList />)
  expect(await screen.findByText(/jane doe/i)).toBeInTheDocument()
})

If you have a test where you want to simulate an error, you override the handler for that one test:

test('shows error on server failure', async () => {
  server.use(
    http.get('/api/users', () => HttpResponse.json({error: 'oops'}, {status: 500}))
  )
  render(<UserList />)
  expect(await screen.findByText(/something went wrong/i)).toBeInTheDocument()
})

This pattern has changed how I write integration tests. I now write tests that render entire features with actual components and actual routing, and the only thing mocked is the network. The tests look almost like end-to-end tests but run in milliseconds because there's no browser.

Note that MSW v2 changed the API — if you're looking at older tutorials with rest.get and res(ctx.json(...)), that's the v1 syntax and it no longer works. The new shape is http.get and HttpResponse.json(...).

Testing React Query (Or TanStack Query, As The Cool Kids Now Call It)

If your app uses React Query, you'll discover that your tests time out for no obvious reason. Then you'll discover that React Query retries failed queries three times by default with exponential backoff. That's great in production. In tests, it means a single failed query takes upwards of seven seconds before your test even sees the error.

The fix is documented in TkDodo's blog (he's a React Query maintainer) and it's the canonical pattern:

function createWrapper() {
  const queryClient = new QueryClient({
    defaultOptions: { queries: { retry: false } }
  })
  return ({ children }) => (
    <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
  )
}

test('shows error on failure', async () => {
  server.use(
    http.get('/api/data', () => HttpResponse.json({}, {status: 500}))
  )
  render(<MyComponent />, { wrapper: createWrapper() })
  expect(await screen.findByText(/error/i)).toBeInTheDocument()
})

Two things to notice. First, you create a fresh QueryClient per test. Don't share one. Tests will pollute each other through the cache. Second, retry: false. Always. In tests, you want immediate failure.

If you forget to wrap your component in a QueryClientProvider at all, you'll get the very recognizable No QueryClient set, use QueryClientProvider to set one error. That one I've seen in roughly seventy percent of "help me debug my test" Slack threads.

Custom Hooks With renderHook

You can test custom hooks directly with renderHook. This used to live in a separate package called @testing-library/react-hooks, which was deprecated in 2022 when renderHook got moved into the main @testing-library/react package starting in version 13.1.

The basic pattern:

import { renderHook, act } from '@testing-library/react'
import { useCounter } from './useCounter'

test('increments the counter', () => {
  const { result } = renderHook(() => useCounter())

  act(() => {
    result.current.increment()
  })

  expect(result.current.count).toBe(1)
})

If your hook needs context, use the wrapper option:

const { result } = renderHook(() => useMyHook(), {
  wrapper: ({ children }) => (
    <MyProvider>{children}</MyProvider>
  )
})

A small honesty note: the new renderHook in @testing-library/react is less full-featured than the old @testing-library/react-hooks package. It doesn't have first-class SSR support. There are some waitForNextUpdate patterns from the old package that have to be rewritten with waitFor. If you migrated and felt like something was missing, you weren't imagining it.

Routing: MemoryRouter Is Your Friend

Testing components that use React Router requires giving them a router. You don't want the real BrowserRouter because that touches window.history, which is shared across tests and causes pollution. You want MemoryRouter, which keeps its history in memory:

import { MemoryRouter, Routes, Route } from 'react-router'

render(
  <MemoryRouter initialEntries={['/users/42']}>
    <Routes>
      <Route path="/users/:id" element={<UserPage />} />
    </Routes>
  </MemoryRouter>
)

The initialEntries prop sets where the router thinks you are. It only takes paths starting with /, not full URLs (this catches people).

If you're testing a component that triggers navigation, you can either render multiple routes and assert that you ended up on the right page (which is how a user would experience it), or you can use the useLocation hook in a test helper component and assert on the location object. The first option is more behavior-focused and is what I usually do.

Vitest Is Eating Jest's Lunch

A note on the surrounding ecosystem because it's been shifting fast. As of 2026, Vitest has effectively passed Jest in adoption for new projects. The State of JS 2024 survey put Vitest at the top for retention and positivity rankings, and the weekly download trend lines crossed sometime in late 2025. Angular 21 (released late 2025) made Vitest the default test runner. Nuxt, SvelteKit, and Astro all recommend it. Jest is not dead — it's still huge, especially in legacy codebases — but the momentum is gone.

For React Testing Library, this matters approximately zero. RTL is test-runner-agnostic. The same render, screen, and userEvent work identically whether you're using Jest or Vitest. The difference is in setup and the matchers.

For Jest, you import jest-dom matchers like this:

import '@testing-library/jest-dom'

For Vitest, you need a slightly different import to register the matchers with Vitest's expect:

import '@testing-library/jest-dom/vitest'

That's about it. The actual test code is identical.

A word of caution: Vitest is not always faster than Jest. There are real-world reports of teams migrating from Jest to Vitest and getting slower test suites, especially with large React codebases. The default Vitest configuration uses Vite's transform pipeline, which can be slower for some setups than Jest's babel-based pipeline. The trick most teams that get fast Vitest results use is happy-dom instead of jsdom for the DOM environment. That alone often cuts test times in half. Your mileage will absolutely vary, so benchmark before you commit to a migration.

If you want one less thing to think about, keep using Jest. If you're starting a new project and using Vite for your build, Vitest is the natural choice. Either is fine.

The Anti-Patterns That Are Killing Your Tests

Let me list, in roughly the order I see them in code review, the things you should stop doing.

Stop using container.querySelector. I know it's tempting. You know CSS selectors. You wrote one in twelve seconds. But every time you do container.querySelector('.btn-primary'), you're testing a class name that has nothing to do with what the user sees. Change the class name during a styling refactor, the test breaks. It also gives the worst error messages of any query type. Use getByRole or one of its siblings.

Stop snapshot testing entire components. I had to learn this one the hard way. We had a snapshot test for a dashboard component that was 640 lines long. Every time anyone changed anything in that dashboard, the snapshot would update, and the reviewer would scan the diff for ten seconds, see that all the changes "looked fine," and approve the snapshot update. We never caught a single bug with that snapshot. We just had a 640-line file in our repo that everyone learned to ignore. The Justin Searls quote that Kent C. Dodds quotes is the eulogy: "Most developers, upon seeing a snapshot test fail, will sooner just nuke the snapshot and record a fresh passing one instead of agonizing over what broke it." That's exactly what we did.

Snapshots have a place. Tiny, focused snapshots of pure functions or deeply structured data are fine. Whole-component snapshots are almost always a smell.

Stop testing component state. If you find yourself writing expect(wrapper.instance().state.count).toBe(1) you're back in Enzyme-land mentally. Test what's on the screen. If clicking the button increments a counter, assert that the displayed text changed from "0" to "1". The user can't see your state. Your test shouldn't either.

Stop testing implementation methods directly. No expect(component.handleSubmit).toHaveBeenCalled(). Test that submitting the form calls the onSubmit prop, or that an API call happens, or that the success message appears. Test the visible outcome.

Stop over-mocking. I saw a test recently that mocked four child components, the routing library, the date library, and a translation hook, all to "isolate" the component under test. By the time all the mocks were set up, the test was longer than the component, the component being tested wasn't really being tested anymore (since most of its actual collaborators had been replaced with stubs), and any refactor that moved logic between components broke the test. The Tahamjp dev.to article from 2025 has my favorite line on this: "Mocks are like duct tape — handy until you start covering the whole car with it."

The right answer most of the time is: don't mock. Render the whole feature with MSW handling network. Let the components actually collaborate. Test what the user sees.

Stop wrapping things in act() that are already wrapped. I covered this above but it's worth repeating. render, fireEvent, waitFor, findBy*, and v14 userEvent are all wrapped internally. Don't double-wrap.

Stop using fireEvent when user-event would do. Just use user-event. The async pattern feels weird at first; you'll get used to it in a week.

Stop ignoring ESLint plugins. There are two: eslint-plugin-testing-library and eslint-plugin-jest-dom. They catch most of the mistakes in this section automatically. Install them, set them to error, and let the linter teach your team.

What's Still Hard in 2026

Honesty time. There are things React Testing Library doesn't do well, and pretending otherwise would be unfair.

Server Components. There is no canonical way to unit-test an async React Server Component. RTL doesn't support them, the React team hasn't published a recommended pattern, and the Next.js documentation explicitly tells you to use end-to-end tests with Playwright instead. If your app is heavily server-rendered, expect a gap in your testing story. This is the single biggest unsolved problem in React testing right now.

Portals. Components that render into a portal (modals, tooltips, popovers built on Radix or Headless UI) sometimes mount outside your test container, and screen.getByRole doesn't find them at first glance. The fix is to use screen queries (which look at document.body, not just the rendered container), or to pass baseElement: document.body to your render. Once you know the trick it's fine, but the first time it happens you'll spend twenty minutes confused.

Animations and motion libraries. framer-motion in particular has a reputation for being slow in jsdom and producing weird test failures. There are open issues going back years. The workarounds usually involve mocking the motion components.

The Suspense regression in React 19. There's an open issue (#1375) where suspended components in tests sometimes keep rendering their fallbacks instead of their children. Affected at one point about 300 tests in the Vercel monorepo. Worth knowing about if you use Suspense heavily.

The npm dependency hell of late 2024. When React 19 went GA, RTL 16.0.x had a peer dependency on @testing-library/dom@^10, but a lot of toolchains (especially Create React App, may it rest in peace) were locked to dom@8. The result was the dreaded ERESOLVE errors and a lot of frantic Stack Overflow questions. RTL 16.1.0 on December 5, 2024 fixed this the same day React 19 shipped, but a lot of people are still on 16.0.1 and don't know why their installs are angry.

A Realistic Test File, From Top To Bottom

Here's what I think a good RTL test file looks like in 2026. This is for a hypothetical login form.

import { describe, test, expect, beforeAll, afterEach, afterAll, vi } from 'vitest'
import { render, screen } from '@testing-library/react'
import userEvent from '@testing-library/user-event'
import { http, HttpResponse } from 'msw'
import { setupServer } from 'msw/node'
import { LoginForm } from './LoginForm'

const server = setupServer(
  http.post('/api/login', async ({ request }) => {
    const body = await request.json()
    if (body.email === 'jane@example.com' && body.password === 'correct') {
      return HttpResponse.json({ token: 'abc123' })
    }
    return HttpResponse.json({ error: 'Invalid credentials' }, { status: 401 })
  })
)

beforeAll(() => server.listen())
afterEach(() => server.resetHandlers())
afterAll(() => server.close())

describe('LoginForm', () => {
  test('logs in with valid credentials', async () => {
    const user = userEvent.setup()
    const onLogin = vi.fn()
    render(<LoginForm onLogin={onLogin} />)

    await user.type(screen.getByLabelText(/email/i), 'jane@example.com')
    await user.type(screen.getByLabelText(/password/i), 'correct')
    await user.click(screen.getByRole('button', { name: /log in/i }))

    await waitFor(() => expect(onLogin).toHaveBeenCalledWith('abc123'))
  })

  test('shows an error with invalid credentials', async () => {
    const user = userEvent.setup()
    render(<LoginForm onLogin={vi.fn()} />)

    await user.type(screen.getByLabelText(/email/i), 'jane@example.com')
    await user.type(screen.getByLabelText(/password/i), 'wrong')
    await user.click(screen.getByRole('button', { name: /log in/i }))

    expect(await screen.findByRole('alert')).toHaveTextContent(/invalid credentials/i)
  })

  test('disables the submit button while submitting', async () => {
    const user = userEvent.setup()
    render(<LoginForm onLogin={vi.fn()} />)

    await user.type(screen.getByLabelText(/email/i), 'jane@example.com')
    await user.type(screen.getByLabelText(/password/i), 'correct')

    const button = screen.getByRole('button', { name: /log in/i })
    await user.click(button)

    expect(button).toBeDisabled()
  })
})

Notice what's not there. No mocks of child components. No assertions on state. No data-testid attributes. No snapshots. No checking that handlers were called with specific internal arguments. Every assertion is something a real user could verify by looking at or interacting with the page. The login flow is tested end to end with real network mocking.

This is the shape of a healthy RTL test file. If your test files don't look like this, that's something to think about.

The Closing Argument

When I started writing React tests with Enzyme, I thought testing was about coverage. Cover every line, cover every branch, sleep at night. When I switched to React Testing Library, I thought testing was about queries — learn the priority list, find the elements the right way, sleep at night.

After a few years, I think testing is mostly about having a good answer to one question: if my application is broken, will my test suite tell me? Not "will some test fail." Not "will coverage drop." Will my tests, the actual ones I wrote with intent, tell me that the user's experience is broken. If yes, the tests are doing their job. If no, they're decoration.

React Testing Library doesn't make this question easier to answer by accident. It makes it easier on purpose, by forcing you to write tests in the language of the user instead of the language of the implementation. That's the whole thing. That's the only reason any of this matters. Every query priority, every async pattern, every anti-pattern in this article — they all come back to that.

Use getByRole. Await your user.click. Wait for things with findBy*. Mock the network with MSW. Don't snapshot anything you wouldn't want to read. Don't reach into state. Don't test children you've already mocked. Trust your tests to fail loudly when something real is broken, and to stay quiet when you're just renaming a variable.

If you do that, you'll spend less of your life arguing with the act warning, and more of your life shipping. Which, last time I checked, is what we're all here for.

Now stop reading and go delete some snapshots.

!!!Hello

DevUnionX — Sat, 25 Apr 2026 17:05:24 +0000

DevUnionX

Apr 25

5 Things AI Can't Do, Even in npm / yarn / pnpm

#npm #devops #ai #programming

21 min read