React18 Batching Patterns — Agent Skill by GitHub

From the author

Provides exact patterns for diagnosing and fixing automatic batching regressions in React 18 class components. Use this skill whenever a class component has multiple setState calls in an async method, inside setTimeout, inside a Promise .then() or .catch(), or in a native event handler. Use it before writing any flushSync call - the decision tree here prevents unnecessary flushSync overuse. Also use this skill when fixing test failures caused by intermediate state assertions that break after React 18 upgrade.

— the description by SaravananRajaraman

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

React 18 introduced automatic batching for async operations, which can break legacy class components that rely on immediate re-renders after setState calls. This skill provides a decision framework to categorize these regressions into three types: logic errors caused by reading stale state after await, independent state updates that can be refactored, and scenarios requiring synchronous rendering via flushSync. It emphasizes refactoring over the use of flushSync to maintain React's performance benefits.

What it does

Provides a diagnostic decision tree for React 18 batching issues.
Defines three categories of batching regressions (A, B, and C).
Offers refactoring patterns to replace stale state reads with local variables.
Explains the correct usage and import syntax for flushSync.
Identifies anti-patterns where flushSync is misused or unnecessary.
Helps resolve test failures caused by intermediate state assertions.

When to use it

When upgrading class components to React 18 and encountering state-related bugs.
When multiple setState calls in async methods, Promises, or timeouts behave unexpectedly.
Before implementing flushSync to ensure it is the appropriate solution.
When fixing test failures that occur after React 18 migration.

Advantages

Prevents unnecessary performance degradation caused by overusing flushSync.
Provides clear, actionable refactoring patterns for common bugs.
Reduces silent state-read bugs by promoting better async state management.
Helps maintain the performance benefits of React 18 concurrent rendering.

Usage examples

“How do I fix a bug where my class component reads this.state after an await and gets the old value?”: The skill guides you to Category A, advising you to remove the conditional state read and use local variables or restructure the logic to avoid relying on intermediate state.
“When is it appropriate to use flushSync in a React 18 class component?”: The skill explains that flushSync should only be used when the user must see an intermediate UI state, such as a loading spinner, before an async operation begins.

Install

Download the skill as a ZIP:
https://mp-staging.autogineer.com/agent-skills/github/react18-batching-patterns/download

Unzip it into the cross-client skills folder of your project:

mkdir -p .agents/skills && unzip react18-batching-patterns.zip -d .agents/skills

Documentation by SaravananRajaraman

React 18 Automatic Batching Patterns

Reference for diagnosing and fixing the most dangerous silent breaking change in React 18 for class-component codebases.

The Core Change

Location of setState	React 17	React 18
React event handler	Batched	Batched (same)
setTimeout	Immediate re-render	Batched
Promise .then() / .catch()	Immediate re-render	Batched
async/await	Immediate re-render	Batched
Native addEventListener callback	Immediate re-render	Batched

Batched means: all setState calls within that execution context flush together in a single re-render at the end. No intermediate renders occur.

Quick Diagnosis

Read every async class method. Ask: does any code after an await read this.state to make a decision?

Code reads this.state after await?
  YES → Category A (silent state-read bug)
  NO, but intermediate render must be visible to user?
    YES → Category C (flushSync needed)
    NO → Category B (refactor, no flushSync)

For the full pattern for each category, read:

references/batching-categories.md - Category A, B, C with full before/after code
references/flushSync-guide.md - when to use flushSync, when NOT to, import syntax

The flushSync Rule

Use flushSync sparingly. It forces a synchronous re-render, bypassing React 18's concurrent scheduler. Overusing it negates the performance benefits of React 18.

Only use flushSync when:

The user must see an intermediate UI state before an async operation begins
A spinner/loading state must render before a fetch starts
Sequential UI steps have distinct visible states (progress wizard, multi-step flow)

In most cases, the fix is a refactor - restructuring the code to not read this.state after await. Read references/batching-categories.md for the correct approach per category.

Files

ATTRIBUTION.mdAdded by AutoGineer903 B
LICENSELicence file added by AutoGineer1.0 KiB
SKILL.md2.4 KiB
references/batching-categories.md5.8 KiB
references/flushSync-guide.md2.4 KiB

references/flushSync-guide.md

flushSync Guide

Import

import { flushSync } from 'react-dom';
// NOT from 'react' - it lives in react-dom

If the file already imports from react-dom:

import ReactDOM from 'react-dom';
// Add named import:
import ReactDOM, { flushSync } from 'react-dom';

Syntax

flushSync(() => {
  this.setState({ ... });
});
// After this line, the re-render has completed synchronously

Multiple setState calls inside one flushSync batch together into ONE synchronous render:

flushSync(() => {
  this.setState({ step: 'loading' });
  this.setState({ progress: 0 });
  // These batch together → one render
});

When to Use

✅ Use when the user must see a specific UI state BEFORE an async operation starts:

flushSync(() => this.setState({ loading: true }));
await expensiveAsyncOperation();

✅ Use in multi-step progress flows where each step must visually complete before the next:

flushSync(() => this.setState({ status: 'validating' }));
await validate();
flushSync(() => this.setState({ status: 'processing' }));
await process();

✅ Use in tests that must assert an intermediate UI state synchronously (avoid when possible - prefer waitFor).

When NOT to Use

❌ Don't use it to "fix" a reading-this.state-after-await bug - that's Category A (refactor instead):

// WRONG - flushSync doesn't fix this
flushSync(() => this.setState({ loading: true }));
const data = await fetchData();
if (this.state.loading) { ... } // still a race condition

❌ Don't use it for every setState to "be safe" - it defeats React 18 concurrent rendering:

// WRONG - excessive flushSync
async handleClick() {
  flushSync(() => this.setState({ clicked: true }));   // unnecessary
  flushSync(() => this.setState({ processing: true })); // unnecessary
  const result = await doWork();
  flushSync(() => this.setState({ result, done: true })); // unnecessary
}

❌ Don't use it inside a useEffect or componentDidMount to trigger immediate state - it causes nested render cycles.

Performance Note

flushSync forces a synchronous render, which blocks the browser thread until the render completes. On slow devices or complex component trees, multiple flushSync calls in an async method will cause visible jank. Use sparingly.

If you find yourself adding more than 2 flushSync calls to a single method, reconsider whether the component's state model needs redesign.

Requirements and compatibility

Written for: GitHub Copilot

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Security

No issues found by our static scan· No issues found

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Implement
Matt Pocock· Community
A structured workflow for implementing software tasks from specifications or tickets.
Software developmentClaude CodeClaude appsOpenAI Codex+14 more
MITGitHub stars of the source repository317.5k
Source Driven Development
Addy Osmani· Community
A rigorous process for grounding code implementation in official, version-specific documentation to ensure accuracy and avoid outdated patterns.
Software developmentClaude CodeClaude appsOpenAI Codex+14 more
MITGitHub stars of the source repository113.9k
Write Swift
Emil Kowalski· Community
A comprehensive guide to writing modern, safe, and performant Swift code following the language's latest idioms and concurrency models.
Software developmentClaude CodeClaude appsOpenAI Codex+14 more
MITGitHub stars of the source repository54.3k
Cardputer Buddy
AnthropicOfficial
Iterate on the Cardputer-Adv MicroPython app bundle (Claude Buddy, Snake, Hello) after the device is already provisioned via m5-onboard. Use when the user wants to add a new app, push a single changed .py without re-flashing, watch device serial logs, or run a one-shot REPL command. Trigger on "add an app", "push to the cardputer", "tail the device", "run on the device", or follow-up work after /maker-setup.
Software developmentClaude CodeClaude appsOpenAI Codex+14 more
Apache-2.0GitHub stars of the source repository46.3k
Typescript Pro
Seth Hobson· Community
An expert TypeScript persona focused on advanced typing, enterprise architecture, and strict type safety.
Software developmentClaude Code
MITGitHub stars of the source repository42.3k
Scala Pro
Seth Hobson· Community
An expert Scala engineer persona specializing in functional programming, distributed systems, and enterprise-grade architecture.
Software developmentClaude Code
MITGitHub stars of the source repository42.3k

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download react18-batching-patterns.zip