✨ EFLx ☁️

First Principles of UI Composition

Sat, 19 Sep 2026 00:00:00 GMT

If you are vibe-coding user interfaces and you are a layperson when it comes to UI/UX, to keep your app from looking like slop, just feed this article to your agents.

There are four levels of components.

Level I: the headless components. They handle all the low-level, tedious, and laborious tasks—the core behavior of a component, its DOM positioning, accessibility, and mobile adaptation (not stylistic adjustments, but things like "Can the context menu be brought up by long-pressing on mobile?"). They don't concern themselves with how the component looks visually; if you use them directly, you'll only get a complex API and an unstyled appearance.
Level II: the design system components, like shadcn/ui. These components form the cornerstone of the entire UI design system, e.g. buttons and cards. They are primarily wrappers around Level I headless components, adding styles that ensure consistency across all components and providing multiple variants.
Level III: the layout components. These components aren't necessarily related to the first two levels, but they abstract the layouts commonly used in your app. Extracting layout components rather than having them scattered throughout the code improves code maintainability and readability. However, this is not a must.
Level IV: the consumer components. These are the components that actually use design system components and layout components to directly build your user interface.

To make your UI code readable and maintainable, here are five minimal rules.

Use shadcn/ui to create a project. Unless you have a solid grasp of the ins and outs, don't mess with it since it's the best and most streamlined architecture you'll ever come across.
When you need to modify a component's styling, think about your design system. If you're completely new to this, just go to https://ui.shadcn.com/create I linked above. It offers simple options that even a novice can use, yet they're powerful enough to create a wide variety of interface styles. Click Get Code – Existing Project to send your customized presets to your agents. Please keep in mind that this is a rare opportunity to experiment with styling while avoiding a sloppy look. Opportunities like this really don't come along very often. Thank shadcn[^1].
If you're determined to do so, or if your agents have convinced you to, you can (allow them to) modify the component styles in shadcn/ui. For experienced developers, shadcn/ui actually encourages this; that's precisely why it's distributed as copyable and modifiable code.
Keep components at each level separate. Keep design system components in components/ui, layout components in components/layout, and consumer components organized within your feature or page modules. As your project grows rapidly, there's no need to rush to strictly extract layout components, but doing so from time to time is very helpful in making you realize just how much your app resembles slop, so you can then correct it. If you create a button with a new style in a consumer component, be careful. You(r agent) should be writing a design system component according to the standards for design system components and reuse it.
When using components, strictly adhere to the "composition" advocated by the design system components. For example, place individual fields inside a FieldGroup rather than using a single div and writing a bunch of Flexbox styles. Consider props like variant, size, etc. before writing className=. If you create design system components other than those from shadcn/ui, please ensure that they also provide out-of-the-box compositions, just like the shadcn/ui components. Your agents are good at mimicking; have them mimic shadcn/ui.

The above assumes you are using Tailwind CSS. If you aren't, you likely won't be able to use shadcn/ui either, but the underlying principles remain the same, and your agents will have no trouble understanding them.

The above assumes you are developing an application in React. If you aren't, the underlying principles remain the same, and your agents will have no trouble understanding them.

The above assumes you know absolutely nothing about UI design but still have some aspirations in that area. If that's not the case, thank you for listening and for your laughter.

[^1]: In addition to shadcn/ui, there are other excellent similar projects out there. If you or your agents are familiar enough with them, it's entirely possible to replace it!

After Safe & Consistent SWR

Sat, 18 Apr 2026 00:00:00 GMT

前段时间，我写了 Safe & Consistent SWR 这篇文章，介绍了在纯客户端的 React 应用中，通过 SWR 或类似库进行数据获取的一种范式。在实践了这种模式两个月后，这一范式的问题也逐渐浮现，并值得理性看待。

事实来源的混乱

随着业务逻辑越来越复杂，数据的“scope”或“endpoint”会越来越多。你需要处理用户、项目、帖子等不同范围的数据和业务逻辑。这时，问题随之显现： SWR 模式通过 Key 来识别某种数据，并在此基础上构建缓存、去重、突变等功能。但是，十个 Endpoint 意味着十个 Key 定义，二十个 Endpoint 意味着二十个 Key 定义。当规模开始增大时，你会开始思考减少模板代码。让我们看看：

在后端，我们通过 /api 或 Electron IPC 或别的什么方式，暴露了各种 CRUD 接口。
在前端 SWR 层，我们为每个 CRUD 接口定义了 Key、获取数据的 SWR 钩子和突变数据的 SWR 钩子和突变数据的钩子。
在前端组件中，我们使用了这些钩子。

貌似没有什么地方可以精简。显然，SWR 层需要手动建立 Key 与后端数据之间的关系，手写某个 CRUD 操作会改变哪些数据。这是令人不适的根源。

一个后端操作会改变什么，这件事归根结底只有后端知道。因此，把“赋予数据 Endpoint、将变更操作与数据突变绑定”这样的任务交给前端，是不合逻辑的。后端才是这些对应关系的事实来源。

tRPC？Server Action？GraphQL？

我首先想到了 electron-trpc。也许这有些倒反天罡，对于一般的 /api 服务器， tRPC 也是可用的方案。然而，这样会带来极大的重构成本，将后端切换到耦合度低的设计时（e.g.，运行 Go 或 Python 服务）更有风险。

那 Server Action 如何呢？我必须坦言，这样做的 DX 是非常好的。在一个“全栈”的 React 应用中，使用 RSC + Server Action 等原语并不是洪水猛兽，事实上这些东西就像米其林餐厅里十万镑一勺的甜点，遇到一些问题时小用一下 RSC 给人的感觉非常舒适和优雅。然而，我们不仅正在讨论具备复杂数据模型的应用——在这种情况下，Server Action 不见得好到哪去——而且，我们还在讨论纯客户端应用的解决方案。

既然后端要保持纯粹，又需要存在一个中间层，这让我们想到了 Codegen。正好，drizzle-orm 还允许我们生成 zod schema，一举两得！在这里，codegen 的意思是根据 Schema 生成 SWR hooks。其实这个想法蛮好的，但是并没有解决突变关联的问题，也就是一个数据变更操作会引发哪些 Key 突变的问题。

最后我们貌似只有 GraphQL 之类的选项了。当我提到 GraphQL 时，它正处于一个很尴尬的境地：如果应用已经很复杂，这意味着和 tRPC 一样高的重构成本。如果应用本身是 toy 级别的，为什么还要这么做呢？为了解决一点点过度设计的问题，我们引入了一个巨大的过度设计的设计……这不好。

略微迷茫

因此，经过许久的思想实验之后，我其实没有对原有架构做出任何足够的改进。不过，在过去两个月里，我已经尝试了：

Service Locator 架构：将 SWR hooks 分类放进“service”对象中，所有 services 以 React Context 形式提供。
一些减少模板代码的 utility，可以快速封装 IPC 函数或者 fetch /api/ 调用。
在旧文章中，我采用基于 { endpoint: ..., /* other params */ } 的 Key 形状。但我发现 TanStack Query 鼓励的基于数组的 Key 甚至可能更好。我曾经假设我有耐心精心控制各个 key 的 mutate，最后发现，当你拥有“所有模型”、“用户添加的模型”、“用户固定的模型”、“真正的所有模型”、“模型列表的所有模型”这些乱七八糟的 Endpoint 之后，你只会在 mutate 里面一网打尽。我正在试验，并且感受到了 ['models', 'pinned'] 而非 { endpoint: 'pinnedModels' } 的正确性。

目前来看，虽然 SWR 层的代码在前端看起来非常庞大，但是它的运行仍然是稳定可靠的。加入一个新功能时，也只需要无脑复制一些模板即可。未来，我可能会发布 Safe & Consistent SWR / Query 的第二版，包含所有更新的最佳实践。就目前为止，我依然认为这样做是最可靠、最有效的数据获取解决方案。

Stateless Agent Matters

Sat, 18 Apr 2026 00:00:00 GMT

The moment the term Agent Harness was coined, it meant the concept had entered the realm of the "named". Once a practice is named—once people realize that existing language cannot precisely describe it and thus borrow a new term—it begins its transition from a "niche" practice to a "best practice".

I still remember the days when people would scramble to pack source code into long-form text, frantically pasting it into the ChatGPT chat box. Even now, amidst the dread of Claude Code launching ten rounds of an Explore Agent, I sometimes copy and paste simple code problems into Google AI Studio just to get a blissfully innocent response.

Regardless, the debate over whether reasoning models require Prompt Engineering has ended. A set of well-crafted prompts and tool schemas can grant a model extraordinary capabilities, and this—in a quiet, unobtrusive way—is becoming the consensus.

Wait. So what is a Stateless Agent?

My perspective originates from a strange sensation regarding "Memory". We first saw memory features in ChatGPT and Google Gemini; later, Claude Code added the so-called MEMORY.md. Some LLM clients, like alma, provided impressive memory functions. On April 16, the new version of OpenAI Codex also introduced memory capabilities.

Actually, the definition of memory is quite broad. Most approaches are relatively "primitive", essentially revolving around one or more text files that the LLM summarizes and updates in the background. There are also "academic" efforts, such as Nowledge Mem, which constructs a vast array of concepts around the aggregation and distillation of memory.

But I started to ponder a question: What is the role of memory in the LLM workflow?

When we ask an LLM to work on a codebase, the process generally looks like this:

The human provides instructions or a goal, perhaps along with constraints and a process. At this point, the model possesses a portion of the context.
The Agent gathers additional context through various means until the context is large enough to reach a certain threshold.
The Agent begins to think about how to proceed, and the context expands further to the next threshold.
Finally, the Agent builds the solution.

Viewed this way, Memory is just a form of context. Context also includes other code in the repository, the Agent's inquiries to the user, and so on.

In communication, people are mainly bothered by two things: the other party's lack of comprehension, and a lack of "tacit understanding" (filling in the missing context). Because LLMs aren't powerful enough yet, redundant context is often used to compensate. This has led to "spec-driven vibe coding"—a programming method that relies on a large volume of descriptions (whether handwritten or AIGC) to ensure the output of vibe coding aligns with the intent. Similarly, people want "tacit understanding," or to maintain consistency, or believe that diachronic accumulation leads to progress. Thus, Memory was introduced.

One could say both approaches are quite correct; practice has proven they yield results. But the problem is: these practices are intended to make an otherwise potentially incorrect result (the product of vibe coding) correct. Therefore, there is more than one way to ensure correctness; furthermore, the real task should be finding the optimal way to ensure that potentially incorrect results become correct.

This is easy to understand: if we only care about whether the LLM outputs correct code, we could just provide increasingly detailed Plans and Specifications, eventually telling it exactly how to write the code. The LLM then merely becomes a tool-caller, responsible for applying that code to the repository.

I know this "limit" (in the mathematical sense) might seem nonsensical, but it proves a point: we should seek effective methods, and simply "making the LLM's output correct" does not necessarily mean effective.

Robert Englander wrote in Engineering Alignment in Probabilistic Generation that the goal of software engineering has always been correctness. LLMs have changed how errors occur. In a probabilistic generation process, correctness degrades at the boundaries between different levels (from Intent to Spec, from Spec to CoT, from CoT to code generation). This degradation manifests as subtle semantic shifts, the filling of implicit assumptions, and the compression of ambiguity. Unlike explicit errors in traditional systems, an LLM-generated system might compile successfully, pass all tests, and run smoothly, yet still have semantically drifted from the original intent.

In that article, the author proposes five planes and emphasizes governing the boundaries between them. But I want to look at this from another perspective. The ontology of an LLM lies in predictive generation, which dictates that n-shot is the most powerful way to influence it. In other words, the content generated by an LLM largely cannot be measured by "correctness." Correctness does not exist within the LLM; it exists within the context. A certain context implies a certain probability distribution of outputs. Relying solely on the "extreme pressure" of context cannot make an LLM 100% generate a specific output, nor does it guarantee that the low-probability "hallucinations" in the distribution will be more "correct."

Correctness doesn't stem from "engineering discipline" either. Specifications don't actually manufacture correctness; they just shift from one error to another, trending toward so-called correctness through a spiral of development. Every "correct" state is actually an "error" relative to the previous harness, and this series does not converge.

If we analyze further, human intent itself carries uncertainty, and there is always a "remnant of the Real" that cannot be described by language. This view might not be popular in software engineering, or even in the natural sciences. But if it is true—and I believe it is—then even without LLM assistance, code written by humans is bound to be not entirely correct.

Therefore, my conclusion is: Correctness is located neither in the LLM nor in the Specification. It resides in the collective effect of all contexts and may also rely on the psyche of the Reviewer.

If this is true, what does it mean? First, we can no longer pin our hopes for correctness on providing a complete, non-deviating intent. This is why I propose the distinction between Stateful and Stateless context. When we write a Specification or introduce memory into the context, we are actually performing a derivation of our intent. This is why I call it "stateful." Memory is derived from historical records; the Spec is derived from the developer’s intent. The Agent no longer thinks in terms of the source code, but instead obeys the state represented by the Spec. In other words, developers are still almost programming manually—only the language has shifted from a programming language to natural language—and they must rely on various constraints to compensate for the limitations of natural language. Moving from Intent to Spec creates a semantic drift at the boundary. When using Memory, one similarly sacrifices the "Markovian" nature of the "here-and-now" intent, hoping the model gains an understanding of the intent's perimeter through historical data.

This is what I find strange.

I believe the context should strictly consist only of my description of intent, and the LLM should be trained to possess this capability: it should be able to identify whether the current context allows it to write sufficiently correct (rather than perfectly correct) code. If it is insufficient, it should use tools like Explore, Ask User, or something like context7 to further acquire context until it is confident.

Why is this the right way? Clearly, people have placed too much focus on "state." The LLM is a black box, but people unconsciously assume it is a black box like a function-where if the input is precise enough, the output will be too. However, the LLM is essentially a Schrödinger-like black box. When this nature surfaces, people start adjusting the input, increasing precision, or introducing diachronicity—adding twelve steps where each step is "precisely" defined, or maintaining a memory file that constantly rolls and updates.

This is actually a neurotic behavior—I say this without malice or intent to attack, because according to psychoanalytic theory, everyone is structured as a neurotic, psychotic, or perverse, may also include autism (categories still debated). The point of highlighting this is to show that such behavior serves to satisfy one's own psychological energy; it aligns with the unconscious desire to be "a bit more precise," "a bit more comfortable," or to "question, overrule, and rebuild." This doesn't mean my proposed method is free of such factors, but when "satisfaction" becomes the substantive drive, I find myself compelled to step back and reflect.

The Stateless Methodology

After the discussion above, my point becomes clear: supplementing context based on Specifications or Memory belongs to a "stateful" derivative practice in the vibe coding realm. A stateless approach, however, relies on the LLM's decision-making ability, keeping the "be a bit more precise" or "question-and-restart" cycle within the Agent Loop itself.

A typical Stateless Agent Loop looks like this:

The user describes the intent, possibly including constraints and processes.
The Agent performs an Explore to obtain facts from the code source.
The Agent may use tools to gain more context, such as reading the documentations.
The Agent asks the user for clarification on key issues.
Steps 2-4 are repeated.
Plan and build up.

This idea coincides with the philosophy of Claude Code or the Claude Agent SDK. If you have experienced a standard Claude Code session, you know the flow is remarkably smooth: you only need basic language skills to describe the task clearly (and concisely), and Claude will gather the information it needs. Sometimes, it stops to ask questions—questions that are often brilliant because they cover exactly what your initial description overlooked, sometimes even suggesting better designs within the question. Then, it generates a Plan and finishes building within minutes.

Of course, the stateless approach has its limitations:

The quality of the codebase must be ensured. For example, if the frontend code does not misuse Tailwind CSS to override component styles, the Agent will notice this while exploring the component’s use cases, learn from this few-shot example, and apply the same practice in subsequent code. Otherwise, one would have to devote extensive sections in Spec to explicitly instruct the agent not to do so.
Sufficient context acquisition methods must be provided. If there are no Agent Skills or tools like context7, knowledge won't appear out of thin air, which limits the ceiling of the LLM's capability.
The LLM must cooperate with us. In trying some models, like OpenAI’s Codex series, I sensed they weren't trained to work this way; a Spec-driven approach suits them better. I suspect this is why Codex App recently added memory features. Meanwhile, models like Claude and GLM excel at the stateless loop.
Excessive consumption of context windows. When the model runs the "explore subagent", the scope is inevitably too broad, which consumes more tokens and time and requires additional inference—though I don't think the spec-driven mode can save on tokens.

Now, only one question remains: in my argument, I specifically pointed out the "vibe coding" scenario. What about other scenarios?

Generalized Vibe Coding: For instance, project management or note organization. The user always needs to provide a Notion MCP to read/write Notion databases, or an Obsidian CLI to access note content. In these cases, the source of truth is external. The model's task is to operate on these external states. This is essentially no different from vibe coding and fits our reasoning above.
Non-generalized Vibe Coding: For example, topics related to personal life. In this case, unless you meticulously list every trivial matter of your life in a memo and, when making a decision or growing, update the memo first and tell yourself "Bingo, Exp+1," then this is clearly a scenario where Memory would shine.

Finally

Thus, we can reach a moderate conclusion. "Stateful" is one approach; "Stateless" is the missing other. For a long time, it has rarely been named or praised, which is one of the reasons I wrote this article.

I have mentioned that some stateful practices are neurotic in nature - but the whole history of software engineering, and even human history, is structurally neurotic, and "neurotic" has become a purely neutral word: type checking, unit testing, formal proof, CI/CD, these are quite great practices.

I do not believe there is a hierarchy between the two methods; the scenarios where Stateless doesn't apply and its limitations are very clear. I promote the Stateless mode out of personal preference, just as others promote Stateful practices. But I have never believed that Stateful should be discarded or that Stateless is the only "correct" way. The purpose of proposing Stateless is to find more paths in the practice of ensuring that the LLM's potentially incorrect outputs become correct—because that is the only way to get one step closer to the truth.

(简体中文) Stateless Agent Matters

Sat, 18 Apr 2026 00:00:00 GMT

Agent Harness 这个词被造出来之后，就意味着它开始进入被人们命名的领域。一旦一种做法开始被人们命名，一旦人们发现语言无法精确地描述，而赋予他一个借用的词汇，他就开始从本质上是“小众”的实践变为“最佳实践”。

我依旧记得在过去，人们通过各种方法，把源码打包进一个长文本，急头白脸地粘贴到 ChatGPT 聊天框中的日子。哪怕现在，带着对 Claude Code 启动十轮 Explore Agent 的恐惧，对一些简单代码问题，我也会复制、粘贴到 Google AI Studio 得到天真无邪的回复。

无论如何，人们结束了推理模型是否需要 Prompt Engineering 的争论，一套 well-crafted 提示词和工具 schema 能让模型获得卓尔不凡的能力，以悄无声息的方式，开始成为人们的共识。

等等。所以什么是 Stateless Agent

我的这种观点起源于一种奇怪的感受，它是关于 Memory 的。最开始我们在 ChatGPT 和 Google Gemini 里面见到记忆功能，Claude Code 也加入了所谓的 MEMORY.md。后来，一些 LLM 客户端比如 alma 提供了令人印象深刻的记忆功能。4 月 16 日，OpenAI Codex 的新版本也加入了记忆功能。

其实对记忆的定义比较广泛。绝大多数做法比较“原始”，比如他们基本上是基于一个或多个文本文件，让 LLM 在后台总结、更新这些文件。也有一些“学院派”的努力，如 Nowledge Mem 围绕记忆的聚合与提炼构造了大量 primitives。

但是我开始思考一个问题：记忆在 LLM 工作流程中的角色是什么？

当我们让 LLM 在代码库中工作时，基本上是这样的流程：

人类提供指令或目的，也许还有约束和过程。此时模型拥有了一部分上下文。
Agent 通过一些方式，收集其它的上下文，直到上下文足够大，达到某一界限
此时 Agent 开始思考怎么做，上下文进一步扩大到下一界限
最终，Agent build up 解决方案。

如果这么看，Memory 是一种上下文。上下文还包括代码库中的其他代码，Agent 中途向用户发起意图询问，等等。

在沟通这件事上，人们主要被两点所困扰。一是对方理解能力差，二是对方和自己没有默契（补全缺失的语境）。 LLM 还不够强大，有时候更冗余的上下文可以弥补这点，于是出现了 spec-driven vibe coding，这主要是通过大量（无论是手写还是 AIGC）类似 Specification 描述，确保 vibe coding 产物符合意图的编程方式。同理，有时候人们希望得到默契，或者希望保持一致性，或是认为历时性的东西可以带来进步。因此，Memory 也加入了。

可以说，这两个做法都是相当正确的，实践已经证明了这样做确实可以带来成效。但是问题是：这些做法意在让原本可能不正确的结果（vibe coding 产物）变得正确，因此，使得结果变得正确的做法也就不止这一种；更甚，在这个问题上，应该做的是寻找最优的、确保可能不正确结果变得正确的这样一个做法。这很好理解：如果我们只关心 LLM 能否输出正确的代码的话，我们只需要提供越来越细致的 Plan 和 Specification，最后干脆告诉他应该怎么写代码，他只负责调用工具，真正将这些代码应用到代码库中。

我知道这个（数学意义上的）“极限”推演可能 makes no sense，但是这能够证明：我们应该寻找有效的方式，而单纯地做到“让 LLM 输出结果变得正确”在这里不完全意味着有效。

Robert Englander 撰写了这篇文章：Engineering Alignment in Probabilistic Generation。他认为，软件工程的目标始终是正确性。LLM 改变了错误发生的方式。在概率性的生成过程中，正确性在不同层级之间的转换边界会发生降级（从意图到 Specification，从 Specification 到 CoT，从 CoT 到生成）。这种降级表现为细微的语义偏移、隐性假设的填充和歧义的压缩。与传统系统的显性错误不同，LLM 生成的系统可能编译成功、通过所有测试、运行平稳，但在语义上已经偏离了最初的意图。

因此，在那篇文章中，作者进一步提出了五大平面，并强调治理他们之间的边界的重要性。但我想从另一个视角看待这个问题。 LLM 的本体论在于预测生成，这决定了 n-shot 是对他最有力的影响方式。换句话说，LLM 生成的内容很大程度上不能用“正确性”去衡量；正确性并不存在于 LLM 中，而是存在于上下文中。某个上下文意味着一些输出的概率分布，单纯地依靠上下文的极限施压不能让 LLM 100% 生成某种输出，甚至不一定意味着在概率分布中，那些小概率的“幻觉”结果会更加“正确”。正确性也不来源于“工程纪律”，Specification 事实上没有制造正确性，只是从一个错误转向另一个错误，在大量的螺旋式发展中趋于所谓的正确，每个正确实际上相对于每前一个 harness 都是“错误”，而这样的级数是不收敛的。

如果进一步分析下去，人的意图本身就带有不确定性，并且总存在无法用语言描述的实在界之剩余。这种观点在软件工程领域不一定受待见，甚至在自然科学领域都不一定。但是，假如真的如此——我相信真的如此——那么，哪怕没有 LLM 辅助，人写的代码也势必不完全正确。

因此，我得出的结论是：正确性不位于 LLM，也不位于 Specification。它位于所有上下文的共同作用，并依赖于 Reviewer 的心理。

如果这是真的，这意味着什么？首先我们不能再寄正确性的希望于提供完整、不偏移的意图上。这是我提出 Stateful / Stateless context 的原因。当我们写 Specification，或者将记忆引入上下文的时候，我们实际上在做一件事：将我们的意图进行了一步派生。从 Intend 到 Specification 是那篇文章所说的一个转换边界，这里产生了语义的漂移，很好理解。使用 Memory 时，同样放弃了“我”的意图的“马尔科夫链”-like 的性质，希望模型通过 Memory 获得对意图周延之后的理解。

这才是我觉得奇怪的地方。

我认为，上下文应该严格地只包括我的意图描述，而 LLM 被训练到应该具备这样的能力：他能够识别目前的上下文是否允许自己写出足够正确（而非完全正确）的代码；如果不够，他应该使用 Explore, Ask User, context7 之类的工具进一步获取上下文，直到自己有把握。

为什么这样做是对的？很显然，人们把过多的注意力放到了状态上。LLM 是黑箱，但人们在无意识中总认为 LLM 是函数式的黑箱，只要输入足够精确，输出也就能足够精确。然而，LLM 本质上是薛定谔那样的黑箱。所以当这种性质浮现时，人们就会开始调整输入，进一步增加输入的精确性，或者引入历时性，引入十二个步骤，每一步都精确一下；或者维护一个记忆文件，不断滚动、更新。这其实是一种神经症行为——我没有恶意，也没有在攻击任何人，因为根据精神分析的理论，任何人不是精神病就是神经症结构（也有可能是变态或孤独症，这些分类尚有争议）。指出这一点的目的在于，指出这种行为只是在 satisfy 人自身的心理能量，符合人无意识中的欲望——再精确一点、再舒适一点，或者质疑、推翻、重建、再质疑。这不意味着我所主张的做法就不包含这种因素，但是当 satisfication 成为实质上的驱力时，我不得不抽出身来思考。

Stateless 方法论

经过上面的讨论，我的观点大概明了了：基于 Specification 或 Memory 补全上下文，在 vibe coding 领域，属于 stateful 的派生形做法。而 stateless 的做法则指望 LLM 拥有决策能力，让“更加精确一点”或“质疑-重来”的循环留在 Agent Loop 内部。

一个典型的 Stateless Agent Loop 是这样的：

用户描述意图，可能还包括约束和过程
进行 Explore，获得代码方面的事实来源
就关键问题询问用户获得 clarification
重复 2-3 步
Plan and build up

这个想法与 Claude Code 或 Claude Agent SDK 的想法不谋而合。如果您体验过一次标准的 Claude Code 作业，会知道这个流程相当丝滑：您只需要具备基本语言能力，清晰（并且务必简洁）地描述任务，然后 Claude 就会搜集他所需要的信息。有时候，他会停下来问出一些问题，这些问题相当牛逼，因为刚好覆盖了你最开始的描述忽略掉的一些点，甚至有时候会在问题中 suggest 更好的设计。然后，他生成一份 Plan，并在几分钟内构建完毕。

当然，stateless 的做法也存在限制：

必须提供足够的获取上下文的方式。假如没有 Agent Skills 或者 context7 之类的东西，知识不会凭空产生，这将限制 LLM 的能力高度。
LLM 必须配合我们。在尝试一些模型时，比如 OpenAI 的 Codex 系列，我明显感知到它并没有被训练地像这样工作，Spec-driven 的方案更适合它。我想这也是为什么 Codex App 最近加入了记忆功能。而 Claude 和 (GLM)[https://z.ai/] 之类的模型则很擅长 stateless loop。

现在，我们只剩下一个问题了：在我的观点中，我明确指出了“vibe coding”这一场景。别的场景呢？

广义 vibe coding：譬如项目管理、笔记整理这样的场景。用户总需要提供 Notion MCP 来读写 Notion 数据库，提供 Obsidian CLI 来访问 Obsidian 笔记内容，等等。在这种情况下，事实来源位于外部，模型的任务是对这些外部状态进行操作，它本质上与 vibe coding 没有区别，适用于我们上面的推理。
非广义 vibe coding：譬如个人相关的话题。在这件事上，除非您将您生活中所有琐碎的事务事无巨细地罗列在备忘录里，并且当您作出决定或成长时，会先更改备忘录然后告诉自己：bingo，经验+1，否则这种场景显然就是 Memory 会大显身手的场景。

最终

所以，我们可以得出温和派的结论了。“Stateful” 是一种做法，“Stateless” 是缺失的另一种。在很长一段时间内，人们很少命名或赞美它，这是我写这篇文章的原因之一。我并不认为两种方法之间有高下之分，Stateless 不适用的场景和限制条件都很清晰。我带着个人喜好推崇 Stateless 模式，就像人们推崇 Stateful 的实践一样，但我从不认为 Stateful 应该被摒弃、Stateless 才是完全正确的。提出 Stateless 的目的仍在于：在试图确保 LLM 可能不正确的输出变得正确的实践中，找出更多的道路，因为这样才能向真理更进一步。

After Safe & Consistent SWR

Fri, 17 Apr 2026 00:00:00 GMT

Some time ago, I wrote Safe & Consistent SWR, which introduced a paradigm for data fetching in pure client-side React applications using SWR or similar libraries. After practicing this pattern for two months, the issues with this paradigm have gradually surfaced, and they deserve a rational look.

The Chaos of the Source of Truth

As business logic becomes more complex, the number of data "scopes" or "endpoints" increases. You need to handle data and business logic for different domains like users, projects, and posts. This is where the problem emerges: The SWR pattern identifies a specific piece of data through a "Key," and builds caching, deduplication, and mutations on top of it. However, ten endpoints mean ten key definitions; twenty endpoints mean twenty key definitions. As the scale grows, you start thinking about reducing boilerplate code. Let's look at the flow:

On the backend, we expose various CRUD interfaces via /api, Electron IPC, or other means.
In the frontend SWR layer, we define the Key, the SWR hook for fetching data, and the SWR hooks for mutating data for every single CRUD interface.
In the frontend components, we use these hooks.

There seems to be nowhere to streamline. Obviously, the SWR layer requires manual effort to establish the relationship between Keys and backend data, manually defining which CRUD operations affect which pieces of data. This is the root of the discomfort.

Ultimately, only the backend knows what a backend operation will change. Therefore, handing the task of "assigning endpoints to data and binding mutation operations to data updates" to the frontend is inherently illogical. The backend is the true source of truth for these mappings.

tRPC? Server Action? GraphQL?

I first thought of electron-trpc. Perhaps it's a bit "heretical," but for general /api servers, tRPC is a viable solution. However, this brings significant refactoring costs and carries risks when switching the backend to a decoupled design (e.g., running a Go or Python service).

What about Server Actions? I must admit, the DX is excellent. In a "full-stack" React app, using primitives like RSC + Server Actions isn't some monster to be feared. In fact, they are like those £10,000-a-spoon desserts in a Michelin-starred restaurant—using RSC sparingly when encountering certain problems feels incredibly comfortable and elegant. However, we are not only discussing applications with complex data models—where Server Actions might not be much better—but also solutions for pure client-side applications.

Since the backend needs to remain "pure" but an intermediate layer is required, Codegen comes to mind. Conveniently, drizzle-orm even allows us to generate Zod schemas, killing two birds with one stone! Here, "codegen" means generating SWR hooks based on a schema. It's actually a good idea, but it doesn't solve the mutation association problem—the issue of which data change operation triggers which Key mutation.

Finally, we are left with options like GraphQL. When I mention GraphQL, it's currently in an awkward spot: if the app is already complex, it means a refactoring cost as high as tRPC. If the app itself is toy-level, why bother? To solve a small problem of over-engineering, we introduce a massive over-engineered design... that's not good.

Slightly Lost

Consequently, after a long period of thought experiments, I haven't actually made any sufficient improvements to the original architecture. However, over the past two months, I have tried:

Service Locator Architecture: Categorizing SWR hooks into "service" objects, with all services provided via React Context.
Boilerplate reduction utilities: Quickly wrapping IPC functions or fetch /api/ calls.
Key Shapes: In my previous article, I adopted a Key shape based on { endpoint: ..., /* other params */ }. But I've found that the array-based Keys encouraged by TanStack Query might even be better. I once assumed I had the patience to meticulously control the mutation of each individual key. In the end, I realized that once you have a mess of endpoints like "all models," "user-added models," "user-pinned models," "true all models," and "all models in the list," you just end up invalidating everything in a single blanket mutation anyway. I am currently experimenting with and feeling the "correctness" of ['models', 'pinned'] over { endpoint: 'pinnedModels' }.

For now, although the SWR layer code looks massive on the frontend, its operation remains stable and reliable. When adding a new feature, you only need to mindlessly copy some templates. In the future, I may release a V2 of Safe & Consistent SWR / Query, including all updated best practices. For now, I still believe this is the most reliable and effective data fetching solution.

Modern React on Client Side

Fri, 23 Jan 2026 00:00:00 GMT

import { Aside } from 'astro-pure/user'

Since C++ 11, features like move semantics, resource management, and functional programming have completely shattered the prejudice that C++ is just "C with Classes." People call this "Modern C++." In fact, the React paradigm has also matured in recent years. I believe that React after version 18 can also be called "Modern React." The updates over these years haven't just been about adding a few Hooks; they represent a continued reform of the paradigm. We are moving from imperatively managing life cycles and state synchronization to declaratively defining resources and behaviors. We are stepping closer to true declarativeness.

Legacy React

In the past, we were accustomed to using useEffect to handle all logic. To "peek" at a state (reading it without wanting it to be reactive), we might have deliberately ignored some dependencies in the dependency array, yet the linter would stop us from doing so. Things like eslint-ignore flooded our code.

Undoubtedly, this leads to code that is difficult to maintain. More insidiously, it confuses the coder's brain—or rather, creates a chaotic understanding of the framework's logic itself. In such a state, the code written can hardly be high-quality, highly readable, or modern.

Moreover, useEffect has deviated from its original intention: to synchronize internal state with external systems. Furthermore, if you are synchronizing an external store, useEffect cannot even be considered a good solution.

To protect performance under the re-rendering mechanism, useCallback and useMemo were also heavily used. This syntactic redundancy exacerbated the issues with dependency arrays and linters.

A Shift in Mental Model: Taking `useEffectEvent` as an Example

In Modern React, useEffect must be reactive. If you need to read a state, but that state change shouldn't trigger the useEffect, you should use useEffectEvent. Here is an example from the official documentation:

function ChatRoom({ roomId, theme }) {
  const onConnected = useEffectEvent(() => {
    showNotification('Connected!', theme)
  })

  useEffect(() => {
    const connection = createConnection(serverUrl, roomId)
    connection.on('connected', () => {
      onConnected()
    })
    connection.connect()
    return () => connection.disconnect()
  }, [roomId])

  // ...
}

showNotification is a behavior, not part of the data flow, so it shouldn't destroy the stability of the Effect. You can use useEffectEvent to call showNotification and use this event inside useEffect without adding it to the dependency array.

However, note that the Effect Event function returned by useEffectEvent can only be used inside Effects (like useEffect).

The example above reflects the deepest philosophy of Modern React: let everything return to its origin. The dependency array should honestly declare reactive dependencies, and developers shouldn't use clever hacks to achieve what are actually common goals.

Similarly, useEffect should only be used to synchronize React state with external systems and shouldn't bear other responsibilities. Although this has been a principle declared by React from the beginning, it is only in the Modern React era that we have enough convenience to fully implement this principle. Let's look further.

Modern Data Fetching and Synchronization

If we use useEffect to fetch data, we need to manually set states like data, isLoading, and error, and manually handle race conditions. This should be viewed as an anti-pattern. It creates a lot of boilerplate code and requires developers to master low-level issues during business development. This not only violates the declarative paradigm but makes it impossible to handle every case perfectly in practice. Moreover, it makes it difficult to implement features essential for modern applications, like caching and debouncing.

According to React philosophy, data should be a resource, not a side effect. Consider the following two points:

Use libraries like SWR or TanStack Query. In Safe & Consistent SWR, I tried to explain the best way to fetch and sync data using query libraries like useSWR. It might be worth a look.
Use useSyncExternalStore. This is a low-level primitive introduced in React 18. When dealing with browser APIs or global state libraries, you no longer need useEffect to listen to and set state.
- Furthermore, it solves issues under concurrent rendering, ensuring that the external data read by the UI is consistent within any given time slice, thus paving the way for the critical feature of concurrent rendering. We will see later how this changes the way we think about component rendering.

Derived State

Have you or people around you written code like this?

function User({ firstName }) {
    const [fullname, setFullname] = useState(null)
    useEffect(() => {
        setFullname(`Kumo ${firstName}`)
    }, [firstName])

    // ...
}

React teaches us that we shouldn't use useEffect here; instead, directly derive state.

function User({ firstName }) {
    const fullname = useMemo(() => `Kumo ${firstName}`, [firstName])
    // ...
}

Wait... something is still not quite right! Every developer should know about the React Compiler. For scenarios where you only want to ensure referential stability, don't waste time manually memoizing anymore.

function User({ firstName }) {
    const fullname = `Kumo ${firstName}`
    // ...
}

Cross-component references and complex Context passing may still cause the Compiler to fail to optimize automatically; once developers lose explicit control over references, debugging difficulty might increase if performance regression occurs. Before switching to it, please also note the two sides of everything.

If you don't need explicit control over memoization behavior, please switch to React Compiler and handle derived state directly and naturally.

Concurrent Rendering

Suppose we have a time-consuming operation. Set a pending state, then show a spinner! This is indeed a very natural thought, but abusing it leads to frequent interface flickering, which in turn requires advanced handling techniques. This raises the barrier to writing good code and forces developers to focus on things they shouldn't have to.

In the concurrent rendering mode, UI updates can be prioritized and can be "suspended."

Components can use use to unwrap a Promise. Before the Promise is resolved, rendering will fall back to the nearest Suspense boundary. This means we can handle asynchronous data just like writing synchronous code. However, this is from a low-level perspective; for actual applications, it is still recommended to handle this via mechanisms like useSWR.

What is Suspense? I recall Suspense wasn't used for this before?

You are right. Suspense has taken on new responsibilities in Modern React, as described above. Once we start using Suspense instead of handling pending states inside components, we can look back at these scenarios:

The user is typing in an input box, while the search and rendering of a Select component have a certain delay.
Fetching data when opening a dropdown menu, but showing a spinner looks bad; passing data via router or context is an anti-pattern.

This means UI rendering can be deferred. useTransition demonstrates how to achieve this. For example, in the data fetching for a dropdown menu, use the { suspense: true } option for useSWR, and then wrap the logic for opening the dropdown menu with startTransition. You can use startTransition to render UI that requires suspense. This won't actually revert to the Suspense boundary; React will mark these updates as non-urgent and will only display the interface once they are completed, thus avoiding the screen flickering issue.

Please be sure to read the Suspense documentation carefully. But trust me, this is still much simpler than the old way!

Additionally, transitions can be widely applied in scenarios requiring non-blocking updates:

function ScrollTracker() {
  const [scrollY, setScrollY] = useState(0)
  useEffect(() => {
    const handler = () => {
      startTransition(() => setScrollY(window.scrollY))
    }
    window.addEventListener(‘scroll’, handler, { passive: true })
    return () => window.removeEventListener(‘scroll’, handler)
  }, [])
}

Encapsulating UI state-updating actions like setScrollY within startTransition ensures updates won't block the UI.

Actions are also usable for Client-Side Apps

Many people say these APIs are brought by RSC (React Server Components), but I don't agree. Even in pure client-side applications, React 19's Action API is still revolutionary.

<form onSubmit={handleSubmit}>
preventDefault inside handleSubmit
setPending(true), maybe considering startTransition after reading the above...?
try/catch POST
setPending(false) / setError(...)
Ah... right! What about optimistic updates? 🤔🤯

I believe you are already disgusted by this boilerplate code. submit, as a mutation of data, shouldn't be this complex.

useActionState automatically manages the result and status of asynchronous operations; you just need to provide a handler function!
useFormStatus allows accessing form status in components like buttons inside the form.
useOptimistic lets us embrace modern UX! Show updates on the UI immediately; if it fails, automatically rollback.

The Final Comparison

Modern React should be able to build applications like this:

const useMessages = (roomId) => useSWR(..., { suspense: true })

function ChatRoom({ roomId }) {
  // messages will not be undefined; let's throw isLoading away
  const { data: messages } = useMessages(roomId)
  const [state, formAction, isPending] = useActionState(sendMessageAPI, null)
  const [optimisticMessages, addOptimisticMessage] = useOptimistic(
    messages,
    (state, newMessage) => [...state, newMessage]
  )

  const activeCount = optimisticMessages.filter(m => !m.archived).length

  return (
    <div>
      <MessageList messages={optimisticMessages} />
      <div className="status">Active: {activeCount}</div>
      
      <form action={async (formData) => {
          const msg = formData.get('message')
          addOptimisticMessage({ text: msg, sending: true })
          await formAction(formData)
      }}>
        <input name="message" />

         {/* use useFormStatus inside; no need to pass states */}
        <SubmitButton />
      </form>
    </div>
  )
}

You might have forgotten that before all this, the universe was chaos, and the Creator gave up on humanity because of messy code.

// Ahh i'm using isSubmitting :(
function SubmitButtonLegacy({ isSubmitting }) {
  return (
    <button type="submit" disabled={isSubmitting}>
      {isSubmitting ? 'Sending...' : 'Send'}
    </button>
  )
}

function ChatRoomLegacy({ roomId }) {
  // Classic Trio!
  const [messages, setMessages] = useState([])
  const [isLoading, setIsLoading] = useState(true)
  const [fetchError, setFetchError] = useState(null)

  useEffect(() => {
    let ignore = false // Handling race conditions
    
    async function fetchData() {
      setIsLoading(true)
      setFetchError(null)
      try {
        const data = await fetchMessagesAPI(roomId)
        if (!ignore) {
          setMessages(data)
        }
      } catch (err) {
        if (!ignore) setFetchError(err)
      } finally {
        if (!ignore) setIsLoading(false)
      }
    }

    fetchData() // Hmm. Honestly, I'd rather use .then.catch.finally

    return () => {
      ignore = true
    }
  }, [roomId]) // My favorite dependency array 🥰

  // Here we go again.
  const [isSending, setIsSending] = useState(false)
  const [sendError, setSendError] = useState(null)

  // We need a ref to prevent closure traps, or use functional updates
  // We need to manually modify messages and rollback on failure
  const handleSendMessage = async (e) => {
    e.preventDefault() // Must prevent default behavior
    const formData = new FormData(e.target)
    const msgText = formData.get('message')
    
    if (!msgText) return

    // Step 1: Optimistic Update
    const tempId = Date.now()
    const optimisticMsg = { id: tempId, text: msgText, sending: true }
    
    setMessages((prev) => [...prev, optimisticMsg])
    setIsSending(true)
    setSendError(null)
    e.target.reset() // Manually clear the form

    try {
      // Step 2: Send Request
      const newServerMsg = await sendMessageAPI(msgText)
      
      // Step 3: Success: Replace temp data with real server data
      setMessages((prev) => 
        prev.map(m => m.id === tempId ? newServerMsg : m)
      )
    } catch (err) {
      // Step 4: Failure: Manual rollback (very easy to get wrong!)
      setSendError(err)
      setMessages((prev) => prev.filter(m => m.id !== tempId))
      // You even need to restore the input box content; omitted here because it's too much trouble
    } finally {
      setIsSending(false)
    }
  }
 
  const activeCount = useMemo(() => {
    return messages.filter(m => !m.archived).length
  }, [messages]) // Carefully writing dependencies.

  // Forgot the skeleton screen again. Whatever, I'll write a Loading text for now
  if (isLoading) return <div>Loading...</div>
  if (fetchError) return <div>Error: {fetchError.message}</div>

  // Finally! After such a long buildup... Wait! Why does such simple UI need such verbose logic? I don't understand 😭
  return (
    <div>
      <MessageList messages={messages} />
      <div className="status">Active: {activeCount}</div>
      <form onSubmit={handleSendMessage}>
        <input name="message" disabled={isSending} />
        <SubmitButtonLegacy isSubmitting={isSending} />
        {sendError && <div className="error">Failed to send</div>}
      </form>
    </div>
  )
}

In summary, in legacy React, to achieve the same functionality, developers need to manually write a massive amount of "glue code" to maintain state consistency. The code volume is not only large, but every manually maintained state is a potential source of bugs.

In this era where framework wars are intensifying, please use less code, greater robustness, and easily do the right thing. Let us vindicate React.

(简体中文) Modern React on Client Side

Fri, 23 Jan 2026 00:00:00 GMT

import { Aside } from 'astro-pure/user'

C++ 11 后，移动语义、资源管理、函数式编程等特性彻底改变了 C++ “带类的 C” 的偏见。人们称其为“Modern C++”。其实，近年来 React 范式也开始走向成熟，我认为 React 18 之后的 React 也可以被称为“Modern React”。这些年来 React 的更新，并非只是多了几个 Hook，而是范式的继续改革。从命令式地手动管理生命周期和状态同步，转向声明式地定义资源与行为。我们离真正的声明式可以更进一步。

传统 React

过去，我们习惯用 useEffect 处理所有逻辑。为了获取“peek”状态（读取状态但不希望这是响应式的），我们可能在依赖数组中刻意忽略一些依赖，然而 linter 又会阻止我们这样做。eslint-ignore 之类的东西充斥在代码中。

这无疑会导致代码变得难以维护，同时更隐性的影响是，他让编码者的大脑混乱，或者说对框架的逻辑本身有着混乱的认知，这样的状态下，写出来的代码必然不可能是高质量、具有高可读性、现代化的。

而且，useEffect 已经偏离了其初衷：用于同步内部状态与外部系统。甚至，如果要同步外部的 store，useEffect 也完全称不上是一个好的方案。

为了保护重渲染机制下的性能，useCallback 和 useMemo 也被大量使用，这种语法冗余的同时也加剧了依赖数组依赖 linter 的问题。

思维模型转变：以 `useEffectEvent` 为例

在 Modern React 中，useEffect 必须是响应式的。如果需要读取某个状态，而该状态变更时又不应该重新触发 useEffect，你应该使用 useEffectEvent。官方文档的示例如下：

function ChatRoom({ roomId, theme }) {
  const onConnected = useEffectEvent(() => {
    showNotification('Connected!', theme)
  })

  useEffect(() => {
    const connection = createConnection(serverUrl, roomId)
    connection.on('connected', () => {
      onConnected()
    })
    connection.connect()
    return () => connection.disconnect()
  }, [roomId])

  // ...
}

showNotification 是一个行为，而非数据的一部分，因此它不应破坏 Effect 的稳定性。可以用 useEffectEvent 来调用 showNotification，并在 useEffect 中使用这个 event 而不需要将其加入依赖数组。

不过需要注意，useEffectEvent 返回的 Effect Event 函数只能用在 Effects 中（如 useEffect）。

上述例子反映了 Modern React 最底层的思想：让一切回归本源，依赖数组就应该诚实地声明响应式的依赖，开发者不应该为实现本来常见的目的而使用奇技淫巧；

同样地，useEffect 也只应该被用作同步 React 状态与外部系统，而不应该承担其他的职责，尽管这是 React 自始至终都声明地原则，但只有 Modern React 时代，我们才有足够的便利实现这一原则。让我们继续往下看。

现代化的数据获取与同步

如果使用 useEffect 来获取数据，我们需要手动设置 data, isLoading, error 等状态，手动处理竞态条件。这样做应该被视为一种反模式。他造成了许多模板代码，还要求业务开发时也要熟练地掌握一些底层问题，这不仅违背了声明式的范式，在实践中要求每处处理都完美得当也是不可能的。更何况这样做还难以实现缓存、去抖动等现代应用所必须的特性。

依照 React 哲学，数据理应是一种资源，而不是副作用。考虑以下两点：

使用 SWR，TanStack Query 等库。在 Safe & Consistent SWR 中，我试图说明使用 useSWR 等 Query 库获取与同步数据的最佳方式，不妨看看。
使用 useSyncExternalStore。这是 React 18 引入的底层原语。对于浏览器 API 或使用全局状态库时，不再需要用 useEffect 去监听和设置状态。
- 而且，它解决了并发渲染下的问题，确保 UI 在任何时间切片读取到的外部数据是一致的，从而为并发渲染这一重要特性开辟道路。在后面我们将会看到这如何改变了组件渲染的思维方式。

派生状态

你或者身边的人是否写过这样的代码？

function User({ firstName }) {
    const [fullname, setFullname] = useState(null)
    useEffect(() => {
        setFullname(`Kumo ${firstName}`)
    }, [firstName])

    // ...
}

React 教导我们，这里不应该用 useEffect，直接派生状态。

function User({ firstName }) {
    const fullname = useMemo(() => `Kumo ${firstName}`, [firstName])
    // ...
}

等等……还是不对劲！所有开发者都应该了解 React Compiler，对于仅仅为了保证引用稳定性的场景，不用再浪费时间手动 memo 了。

function User({ firstName }) {
    const fullname = `Kumo ${firstName}`
    // ...
}

跨组件引用、复杂的 Context 传递依然可能导致 Compiler 无法自动优化；开发者失去对引用的显式控制权后，一旦出现性能回退，调试的难度反而会上升。在改用它之前，也请你注意任何事物都具有的两面性。

如果不需要明确的对 memorization 行为的控制，请改用 React Compiler 并直接自然地处理派生状态。

并发渲染

假设我们有一个耗时操作。设置一个 pending 状态，然后显示一个 spinner！这的确是很自然的想法，然而滥用会导致界面频繁闪烁，从而要求更高级的处理技巧，这又提高了写出好代码的门槛，而且让开发者的注意力集中在本不应该的事情上。

在并发渲染的模式中，UI 的更新是可以分优先级的，且可以被“挂起”的。

组件可以用 use 解包 Promise，在 Promise resolved 前，渲染会回退到最近的 Suspense 边界。这意味着我们可以像写同步代码一样处理异步数据，不过，这是从底层层面而言的；对于实际应用，还是建议通过 useSWR 等机制来处理。

什么是 Suspense？我记得 Suspense 以前不是干这个的吧？

你说得没错。Suspense 在 Modern React 中承担起了新的职责，正如上面所述。一旦开始使用 Suspense 而不是在组件内处理 pending 状态，我们就可以回头看看这些场景：

用户在输入框打字，然而 Select 组件的搜索和渲染带有一定延迟
打开 dropdown menu 时需要抓取数据，但显示一个 spinner 显然观感不好；让 router 或 context 传递数据又是反模式

这意味着 UI 渲染是可以延后的。useTransition 展示了如何做到这一点。例如，在 dropdown menu 的数据获取中，为 useSWR 使用 { suspense: true } 选项，然后用 startTransition 包裹打开 dropdown menu 的逻辑。你可以用 startTransition 来渲染需要 suspense 的 UI，而这不会真的回到 Suspense 边界；React 会标记这些更新为非紧急，只有在完成后才会显示界面，从而避免了屏幕闪烁的问题。

请务必仔细阅读 Suspense 的文档。不过相信我，这仍然会比旧的方式简单很多！

此外，transitions 可以广泛地应用于需要不阻塞地更新的场景：

function ScrollTracker() {
  const [scrollY, setScrollY] = useState(0)
  useEffect(() => {
    const handler = () => {
      startTransition(() => setScrollY(window.scrollY))
    }
    window.addEventListener('scroll', handler, { passive: true })
    return () => window.removeEventListener('scroll', handler)
  }, [])
}

把 setScrollY 这种操作 UI 状态的行为封装进 startTransition，就能确保更新不会 block UI 了。

Action 同样可用于客户端应用

很多人说这些 API 是 RSC 带来的，我并不认可。即使在纯客户端应用中，React 19 的 Action API 依然极具革命性。

<form onSubmit={handleSubmit}>
在 handleSubmit 里 preventDefault
setPending(true)，或许看了前面的内容会考虑 startTransition...?
try/catch POST
setPending(false) / setError(...)
啊……对！还有乐观更新该怎么办 🤔🤯

相信你已经对这些模板代码感到反感。submit 作为数据的 mutation，不应该这么复杂。

useActionState 自动管理异步操作的结果和状态，只需要提供一个处理函数就行！
useFormStatus 在 button 等 form 内组件访问 form 状态。
useOptimistic 让我们拥抱现代化 UX！立即在 UI 上显示更新；如果失败，自动回滚。

最终的对比

现代 React 应该能够这样构建应用：

const useMessages = (roomId) => useSWR(..., { suspense: true })

function ChatRoom({ roomId }) {
  // messages 不会是 undefined，可以把 isLoading 扔了
  const { data: messages } = useMessages(roomId)
  const [state, formAction, isPending] = useActionState(sendMessageAPI, null)
  const [optimisticMessages, addOptimisticMessage] = useOptimistic(
    messages,
    (state, newMessage) => [...state, newMessage]
  )

  const activeCount = optimisticMessages.filter(m => !m.archived).length

  return (
    <div>
      <MessageList messages={optimisticMessages} />
      <div className="status">Active: {activeCount}</div>
      
      <form action={async (formData) => {
          const msg = formData.get('message')
          addOptimisticMessage({ text: msg, sending: true })
          await formAction(formData)
      }}>
        <input name="message" />

         {/* 内部使用 useFormStatus，无需传递状态 */}
        <SubmitButton />
      </form>
    </div>
  )
}

你可能已经忘了在这一切以前，宇宙是一片混沌，造物主因为 messy code 放弃了人类。

// 继承 isSubmitting 状态 :(
function SubmitButtonLegacy({ isSubmitting }) {
  return (
    <button type="submit" disabled={isSubmitting}>
      {isSubmitting ? 'Sending...' : 'Send'}
    </button>
  )
}

function ChatRoomLegacy({ roomId }) {
  // 经典三件套！
  const [messages, setMessages] = useState([])
  const [isLoading, setIsLoading] = useState(true)
  const [fetchError, setFetchError] = useState(null)

  useEffect(() => {
    let ignore = false // 处理竞态条件
    
    async function fetchData() {
      setIsLoading(true)
      setFetchError(null)
      try {
        const data = await fetchMessagesAPI(roomId)
        if (!ignore) {
          setMessages(data)
        }
      } catch (err) {
        if (!ignore) setFetchError(err)
      } finally {
        if (!ignore) setIsLoading(false)
      }
    }

    fetchData() // 嗯。说实话我还不如用 .then.catch.finally

    return () => {
      ignore = true
    }
  }, [roomId]) // 我最爱的依赖数组 🥰

  // 又来。
  const [isSending, setIsSending] = useState(false)
  const [sendError, setSendError] = useState(null)

  // 我们需要一个 ref 来防止闭包陷阱，或者使用函数式更新
  // 我们需要手动修改 messages 并在失败时回滚  
  const handleSendMessage = async (e) => {
    e.preventDefault() // 必须阻止默认行为
    const formData = new FormData(e.target)
    const msgText = formData.get('message')
    
    if (!msgText) return

    // 第一步 乐观更新
    const tempId = Date.now()
    const optimisticMsg = { id: tempId, text: msgText, sending: true }
    
    setMessages((prev) => [...prev, optimisticMsg])
    setIsSending(true)
    setSendError(null)
    e.target.reset() // 手动清空表单

    try {
      // 第二步 发送请求
      const newServerMsg = await sendMessageAPI(msgText)
      
      // 第三步 成功：用服务器返回的真实数据替换临时数据
      setMessages((prev) => 
        prev.map(m => m.id === tempId ? newServerMsg : m)
      )
    } catch (err) {
      // 第四步 失败：手动回滚（非常容易写错！）
      setSendError(err)
      setMessages((prev) => prev.filter(m => m.id !== tempId))
      // 甚至还需要把输入框的内容恢复回去，这里省略了，太麻烦
    } finally {
      setIsSending(false)
    }
  }
 
  const activeCount = useMemo(() => {
    return messages.filter(m => !m.archived).length
  }, [messages]) // 小心翼翼写依赖。

  // 骨架屏又忘记做了。算了写个 Loading 以后再说
  if (isLoading) return <div>Loading...</div>
  if (fetchError) return <div>Error: {fetchError.message}</div>

  // 终于！吟唱了那么久，终于……不对！这么简单的 UI，为什么需要如此冗长的逻辑？我不理解 😭
  return (
    <div>
      <MessageList messages={messages} />
      <div className="status">Active: {activeCount}</div>
      <form onSubmit={handleSendMessage}>
        <input name="message" disabled={isSending} />
        <SubmitButtonLegacy isSubmitting={isSending} />
        {sendError && <div className="error">Failed to send</div>}
      </form>
    </div>
  )
}

总而言之，在传统 React 中，为了实现同样的功能，需要开发者手动编写大量的“胶水代码”来维护状态的一致性。代码量不仅大，而且每一个手动维护的状态都是潜在的 Bug 来源。

在这个框架之争愈演愈烈的时代，请用更少的代码，更强的鲁棒性，easy 地做正确的事，让我们为 React 正名。

Safe & Consistent SWR / TanStack Query

Sat, 17 Jan 2026 00:00:00 GMT

import { Aside, Spoiler } from 'astro-pure/user'

Why does this matter?

This article focuses on purely client-side applications. We aren't discussing React Server Components (RSC) or Server Functions here. We are dealing with scenarios where data fetching and mutation logic happen entirely within the browser's rendering lifecycle.

In reality, many developers are still manually managing states like data, isLoading, and error, utilizing useEffect to fetch data. I don't need to lecture you on why that's brittle; by using libraries like useSWR or others, we can implement these features more naturally while enjoying benefits like caching, global mutation, and request deduplication.

For the sake of convenience, I'll use SWR for the examples below. These libraries use a "key" to manage the cache. If a "key" already has corresponding data, all useSWR hooks using that same "key" will share that data state. You can "mutate" a specific "key," causing all subscribers to re-fetch and update based on their memoization strategies. The "key" can be an array or an object. This allows us to embed the parameters required for the request directly into the key, letting the fetcher extract them. This handy feature saves us from constantly rebuilding callbacks via useCallback.

The problem lies in inconsistency

Based on the features above, we can identify several potential pitfalls:

Is the key strictly 1:1 with the fetcher? If not, chaos ensues. Global mutations might fail silently (e.g., you think you mutated the correct key, but a component somewhere else is bound to a slightly different key structure).
Is the key format standardized across the project? Without a standard, maintainability plummets.
Is it decoupled enough? If you write (key) => updateUserName({ id: key[0], name: key[1] }) directly as your fetcher, a simple change to the key structure or the backend API signature could trigger a massive refactoring headache.

Therefore, we need a unified component (or pattern) to manage the relationships between these keys, data fetching functions, mutation behaviors, and the targets of those mutations. It's actually easier than it sounds. (Confident.jpg)

Registering Keys and Fetchers

First, let's establish a mental model:

The source and type of the data will be called the endpoint. If you've written an SWR key like ['user', ...], then user is the endpoint.
Let's say you have a user endpoint. If you want to fetch a list of all users (perhaps with filters), you should separate that into a distinct endpoint like users, userList, or allUsers. Do not reuse the singular user endpoint. Furthermore, any given endpoint should map 1:1 to a specific fetcher function. Whether you split endpoints fundamentally depends on your backend implementation.
A key often includes a scope, which refers to a specific constraint, such as a User ID.

Let the battle with the TypeScript type system begin!

Ideally, the frontend should be able to generate a key like this:

useSWR(userKey({ scope: userId, ... }), ...)

In this case, userKey would be a function that accepts TParams and returns { endpoint: 'user' as const } & TParams.

To simplify this and enforce a standard construction method, we can write a quick factory function. Interestingly, we can inject a $inferParams (and also $inferKey!) property via type assertion. This allows us to access that " TParams " type later using typeof userKey.$inferParams. You'll see why this is useful in a moment. I learn this from drizzle-orm. Thanks!

const createKey =
  <TParams extends Record<string, unknown> = { scope: string }>() =>
  <const T>(endpoint: T) => {
    const fn = (params: TParams) => ({
      endpoint,
      ...params,
    })

    return fn as ((params: TParams) => { endpoint: T } & TParams) & {
      $inferParams: TParams,
      $inferKey: { endpoint: T } & TParams
    }
  }

When no generic parameter is provided, it defaults to requiring a scope in the key construction. Usage looks like this:

const userKey = createKey()('user')

If an endpoint requires more parameters to fetch data, we define it like this:

const userKey = createKey<{
  scope: string
  organization: string
}>()('user')

If we put the endpoint type const T at the "top" of the function definition alongside the params, TypeScript (I really hate these rituals to please the compiler...) fails to infer the endpoint type automatically 😱.

I recommend defining the key type simultaneously with the key creator. This gives us some useful union types for later use.

export type AppSWRKeys = typeof userKey.$inferKey
export type AppSWREndpoints = AppSWRKeys['endpoint']

Following SWR best practices—and to abstract the choice of fetcher away from the UI components—let's define a dedicated 👑 hook for the user. Here is where .$inferParams shines by simplifying our type definitions 🥰.

const useUser = (params: typeof userKey.$inferParams, config?: SWRConfiguration) =>
  useSWR(userKey(params), ({ scope: id }) => getUserById({ id }), config)

Let's compare fetching user data before and after this transformation:

// Before SWR
const [data, setData] = useState<...>()
const [error, setError] = useState<...>()
const [loading, setIsLoading] = useState<...>()
useEffect(() => {
  getUserById({ id: userId }).then(data => setData(data)).catch(...).finally(...)
}, [userId]) // ❌ Manually handling lifecycle via useEffect

// Naive SWR usage
// ❌ Closure captures external 'userId', avoiding useCallback/dependency array check issues, but it's brittle.
const { data, error, isLoading } = useSWR(['user', userId], () => getUserById({ id: userId }))

// ❌ No unified constraints on key construction or how the fetcher receives args.
const { data, error, isLoading } = useSWR(['user', userId], ([_, id]) => getUserById({ id }))

// The Refactored Way
// ✅ Auto-completion, consistent keys, no need to specify fetcher manually.
const { data, error, isLoading } = useUser({ scope: userId })

How about that? Everything just became clearer.

If the logic for fetching user data changes, you only update the useUser definition.
You don't need to dig through massive API docs to remember which endpoint to call.
You don't need to think about how to structure the SWR key. Or rather, we moved that cognitive load upfront to when useUser was defined.
It looks clean and concise! ✨

Handling Mutation and Optimistic Updates

Directly await-ing an operation function or POSTing to the backend inside your component is common behavior—but it's bad practice. If you forget to mutate (revalidate), your UI state becomes stale. If the UI doesn't update, your user might start poking their iPad screen aggressively, potentially generating more hardware revenue for Apple! Or perhaps they'll choose the gentle approach: spamming the refresh button... effectively launching a DDoS attack on your API 🤔?

The best practice remains separation of concerns. Since we can't expect frontend developers to remember to mutate every single time, let's expose a trigger function from a hook that handles the mutation internally.

Obviously, we need some utility functions first. For example, a helper to globally mutate any useSWR keys that match a specific condition:

type KeyMatcher = { key: Partial<AppSWRKeys>; data?: unknown }

const isPartialMatch = (
  target: Record<string, unknown>,
  partial: Record<string, unknown>,
) => {
  if (typeof target !== 'object' || target === null) return false
  return Object.keys(partial).every(
    (k) => k in target && target[k] === partial[k],
  )
}

export const mutateGlobal = async (matchers: KeyMatcher | KeyMatcher[]) => {
  const conditions = Array.isArray(matchers) ? matchers : [matchers]
  
  await Promise.allSettled(
    conditions.map((c) =>
      mutate((cacheKey: AppSWRKeys) => {
        if (typeof cacheKey !== 'object' || cacheKey === null) return false
        return isPartialMatch(cacheKey, c.key)
      }, c.data),
    ),
  )
}

Usage:

await mutateGlobal({ key: ..., data: ... /* 'data' is optional, used for optimistic updates */ })

Since we unified our mental model earlier, implementing the required mutation hook is now trivial.

function useUpsertUser(scope: string) {
  const { trigger } = useSWRMutation(
    userKey({ scope }),
    (
      key,
      {
        arg,
      }: {
        arg: Parameters<typeof upsertUser>[0]
      },
    ) => upsertUser(arg),
    {
      onSuccess: (data) =>
        mutateGlobal([
          { key: { endpoint: 'user', scope }, data }, 
          { key: { endpoint: 'users' } }
        ]),
    },
  )

  return { upsertUser: trigger }
}

This component is tightly coupled with business logic (backend API calls, function signatures, specific mutation conditions, etc.), thus we won't abstract it further.

You can also add other data actions to this hook so the frontend can access them quickly.

Furthermore, optimistic updates have become an essential consideration in modern app developments. Remember to use the data property in the mutateGlobal matcher. Please note this relies on that the action succeeded with a returning. If a "real" or "immediate" optimistic update is needed, put the optimistic data in trigger function. Users will see the UI react instantly, faster than any shooting star 🌠 preventing them from making a wish on your loading spinner! You can also add onError handling or allow the frontend to pass optional options that get piped through to useSWRMutation.

Summary

The key to everything lies in establishing a unified, consistent mental model. Isolate the messy logic into a separate layer and leverage the power of React hooks. Let me wish this helps you build safe, sustainable code before LLMs ruin your c...ode.... bro that's not funny.

✨ EFLx ☁️

First Principles of UI Composition

After Safe & Consistent SWR

事实来源的混乱

tRPC？Server Action？GraphQL？

略微迷茫

Stateless Agent Matters

Wait. So what is a Stateless Agent?

The Stateless Methodology

Finally

(简体中文) Stateless Agent Matters

等等。所以什么是 Stateless Agent

Stateless 方法论

最终

After Safe & Consistent SWR

The Chaos of the Source of Truth

tRPC? Server Action? GraphQL?

Slightly Lost

Modern React on Client Side

Legacy React

A Shift in Mental Model: Taking useEffectEvent as an Example

Modern Data Fetching and Synchronization

Derived State

Concurrent Rendering

Actions are also usable for Client-Side Apps

The Final Comparison

(简体中文) Modern React on Client Side

传统 React

思维模型转变：以 useEffectEvent 为例

现代化的数据获取与同步

派生状态

并发渲染

Action 同样可用于客户端应用

最终的对比

Safe & Consistent SWR / TanStack Query

Why does this matter?

The problem lies in inconsistency

Registering Keys and Fetchers

Handling Mutation and Optimistic Updates

Summary

A Shift in Mental Model: Taking `useEffectEvent` as an Example

思维模型转变：以 `useEffectEvent` 为例