`. You don't nest `` inside ``; you nest a geometry and a material inside a mesh.
```tsx
import { Canvas } from '@react-three/fiber';
function Box() {
return (
);
}
export function Scene() {
return (
);
}
```
Read that and the uncanny thing is how *ordinary* it is. It's components. `` is a component you could reuse, wrap in a list, conditionally render. `rotation` and `color` are just props — drive them from state and the cube animates or recolors, because it's the same reactivity you've used all series. `` is to a 3D renderer what `` is to the DOM renderer: a primitive the renderer knows how to draw. Everything you know about composing React components — props down, state-driven rendering, reuse, hooks — applies unchanged. Only the primitives at the bottom of the tree are different.
## VR and AR Are Just More of the Same Realization
Once you accept that React can describe a 3D scene, VR and AR stop being a separate leap. A VR headset is, from the code's point of view, a 3D scene rendered in stereo with head tracking. AR is a 3D scene composited over a camera feed. The *scene* — the tree of meshes and lights and cameras — is the same tree React Three Fiber already renders; the WebXR layer adds the headset and the tracking on top.
So the progression is one idea extended, not three separate technologies to learn. Describe a 3D scene as a React tree. Render that tree to a screen — that's 3D on the web. Render it to a headset in stereo — that's VR. Composite it onto the real world — that's AR. At every step the component model is identical; what changes is the output device, exactly the way it changed when we went from browser tab to [desktop window](/blog/react-playbook-desktop) to [native phone](/blog/react-playbook-react-native). Same React, different target. You are not learning 3D-React and then VR-React and then AR-React. You are learning that React describes a tree, and the tree can be pointed at increasingly immersive places.
## The Thing This Whole Series Was Actually About
I saved this topic for last on purpose, because it makes the through-line of everything before it visible.
Look back at what we did. We fetched data and let a renderer reconcile the result. We managed state and let components re-render as a function of it. We moved React onto the desktop, onto phones, and now into three-dimensional space — and at every single stop, the *same* mental model carried: describe what the UI should be for a given state, and let a renderer make it real on whatever the target happens to be. The target was a browser, then a native window, then a native view, then a scene graph. The model never changed. That's not a coincidence you stumble on at article thirty — it's the thing the whole series was quietly teaching under the cover of specific problems.
> React is not a DOM library. It is a way of describing UI as a function of state, with a renderer that reconciles your description against some target. The DOM was always just the first target.
That's why a React developer can move across this entire landscape — web, desktop, mobile, 3D, immersive — without starting over each time. The specifics are real and each one takes genuine learning, as every article in this series insisted. But the foundation is portable in a way that's rare in software, and 3D is the clearest proof: the moment `
` becomes `
` and *nothing else about how you think has to change*, you understand what you actually learned. You didn't learn the DOM. You learned React.
## How I'd Approach It — and Where the Series Lands
Strip it to decisions:
- **3D isn't a hack on top of React.** A scene is a tree, React renders trees, and React Three Fiber makes the elements 3D objects. `` is the new ``.
- **Your whole component model transfers.** Props, state, hooks, composition, reuse — all unchanged. Only the leaf primitives differ.
- **VR and AR are the same tree, a different output device.** Screen, headset, camera-composited world. Learn the scene, not three separate stacks.
- **The portable asset was never the platform.** It's the model: UI as a function of state, reconciled by a renderer against a target.
And that's where I'll leave the React Playbook. Thirty articles, from spinning up a project to rendering a cube in VR, and the honest summary of all of them is smaller than the page count suggests: pick tools that own the messy edges, keep your source of truth in one place, treat the client as untrusted and the boundary as sacred, and describe your UI as a function of state so it can follow you to whatever comes next. The specific libraries will churn — some of the ones I recommended will be replaced, and that's fine. The way of thinking is the part that lasts, and if this series left you with that instead of a list of dependencies, it did its job.
Thanks for reading this far. If the Playbook changed how you approach even one of these problems — or if you disagree with where I landed on some of them, which is entirely fair — I'd genuinely like to hear about it. That's the conversation that makes writing thirty of these worth it.
---
# React Native: What 'Learn Once, Write Anywhere' Really Means
Canonical: https://ma-x.im/blog/react-playbook-react-native
Author: Maksym Kuzmitskyi
Published: Jun 09, 2026
The single most useful thing to get straight about React Native is a slogan, and it's one people consistently misquote. The promise was never "write once, run anywhere." It was "*learn* once, write anywhere" — and the difference between those two words is the entire reason web developers either love React Native or feel betrayed by it.
Because here's what actually transfers to mobile: your React knowledge. Components, props, state, hooks, the mental model of describing UI as a function of data — all of it, intact, on day one. You are not starting over. What does *not* transfer is a lot of your code and, more subtly, a lot of your instincts. The `
` you've typed a hundred thousand times doesn't exist. CSS as you know it doesn't exist. The layout habits your fingers have memorized quietly stop working. So you arrive on mobile fluent in the language and unfamiliar with the streets, and whether that feels empowering or frustrating comes down entirely to expecting it.
This article is about drawing that line honestly — what your React experience genuinely buys you on mobile, and where it stops — so you show up expecting "learn once," not "write once," and don't waste a week being angry at the wall.
## There Is No DOM. That's the Whole Shift.
Start with the concept that reorganizes everything else: React Native does not render to a browser, because there is no browser. Your components render to *actual native platform views* — a real iOS `UIView`, a real Android widget. React is the engine describing the UI; the thing it draws is native, not HTML.
This is why the primitives change. You don't write `
` and `
` and ``, because those are HTML and there's no HTML here. You write `` and ``, which map to genuine native components:
```tsx
import { View, Text, Pressable } from 'react-native';
export function Greeting({ name }: { name: string }) {
return (
Hi {name}
console.log('tapped')}>
Tap me
);
}
```
Notice how *familiar* the shape is — it's components, props, a style prop, an event handler. And notice how many small things are different: `View` not `div`, `Text` wrapping every piece of text (you can't just drop a bare string like in HTML), `onPress` not `onClick`, `Pressable` instead of a `button`. That's "learn once, write anywhere" in miniature — the *shape* of your React knowledge fits perfectly, and every *specific* has to be relearned. The engine is the same; the vocabulary is new.
## Styling: It Looks Like CSS and Isn't
The place this bites hardest, and the one worth dwelling on, is styling — because it looks close enough to CSS that you trust it, then it violates that trust.
React Native styling *resembles* CSS: you write style objects with camelCased properties, and many familiar names work. But it is not CSS, and the differences are exactly the ones your instincts will trip over. There are no cascading stylesheets, no selectors, no inheritance in the way you rely on — styles are explicit, per-component objects. There's no `display: block` versus `inline`. Most jarring of all: **everything is flexbox, and it's vertical by default.** On the web, `flexDirection` defaults to `row`; in React Native it defaults to `column`, because a phone screen is tall. Your web layout muscle memory, built on horizontal-by-default flow, is subtly wrong on every screen until you internalize the flip.
```tsx
import { StyleSheet } from 'react-native';
const styles = StyleSheet.create({
card: {
// flexDirection defaults to 'column' here — the opposite of the web.
padding: 16,
backgroundColor: '#fff',
},
title: { fontSize: 18, fontWeight: '600' },
});
```
None of this is hard. It's just *different*, and the danger is precisely that it looks similar enough that you don't respect the difference and spend an afternoon confused why your row is a column. Expect styling to be "CSS-flavored, not CSS," and the friction drops away. Treat it as the CSS you know and it will quietly punish you.
## Just Use Expo
A practical fork, stated plainly because it saves the most pain: when you start a React Native project, use [Expo](https://expo.dev). Bare React Native drops you into native build toolchains — Xcode, Android Studio, native dependency management — which is a heavy, platform-specific world that has nothing to do with React and everything to do with mobile plumbing you didn't sign up to learn on day one.
Expo is to React Native roughly what [a good meta-framework is to React on the web](/blog/react-playbook-starting-new-project): it owns the miserable setup and configuration so you can stay in the part you're good at. It handles the build tooling, gives you a clean managed workflow, and bundles access to native device APIs — camera, location, notifications — behind simple JavaScript, so reaching for the camera doesn't mean touching native code. It's the same lesson this whole series keeps landing on: don't hand-assemble the plumbing when a well-made tool already owns it. For the overwhelming majority of apps, Expo is simply the right starting point, and starting bare is a choice you should have a specific reason for.
## The Instinct That Actually Needs Retraining
Beyond the vocabulary, there's a deeper adjustment, and it's the one that separates a web app running on a phone from an app that belongs there. **Mobile is not a small desktop, and users can feel the difference instantly.**
Touch is not a mouse. There's no hover — a whole category of web interaction just doesn't exist, and designs that lean on it fall flat. Targets have to be finger-sized, not cursor-precise. Gestures — swipe, long-press, pull-to-refresh — are expected vocabulary, not enhancements. Platform conventions differ, and iOS and Android users each have expectations about how navigation and controls should feel that a lowest-common-denominator layout ignores at its peril. And the device itself imposes realities the desktop rarely forces you to think about: constrained screens, variable network, battery, memory. The web developer's instinct to fill horizontal space, to treat the network as reliable, to assume hover and precise pointing — those instincts need retraining, and the app quality lives in that retraining far more than in the syntax.
This is the honest edge of "learn once, write anywhere": your React *transfers*, but your sense of what a good interface *is* has to expand from the web's assumptions to the phone's. That's not a knock on React Native — it's the reality of the platform being genuinely native, which is the whole point of using it.
## How I'd Approach It
Strip it to decisions:
- **It's "learn once," not "write once."** Your React knowledge transfers whole; a lot of your code and instincts don't. Expect that and the wall becomes a curriculum.
- **There is no DOM.** `View` and `Text`, not `div` and `span`; `onPress`, not `onClick`. You render to real native views.
- **Styling is CSS-flavored, not CSS.** No cascade, no selectors, flexbox everywhere, and column-by-default. Respect the difference instead of trusting the resemblance.
- **Use Expo.** It owns the native build plumbing so you stay in React. Go bare only with a specific reason.
- **Retrain your interface instincts.** Touch, gestures, finger targets, platform conventions, device limits — mobile is native, not a narrow desktop.
The reason React Native either delights or frustrates comes down to which promise you showed up believing. Arrive expecting "write once, run everywhere" and every difference feels like a broken promise. Arrive expecting "learn once, write anywhere" and the exact same differences feel like a reasonable tax on real native rendering — you keep the expensive thing, your React fluency, and pay for the platform specifics, which is a genuinely good trade. The knowledge is the asset. The code was always going to be somewhat local to where it runs.
For the final article, the series leaves flat screens behind completely: [React in VR and AR](/blog/react-playbook-vr-ar) — where the same component model gets pointed at three-dimensional space, and what it means to write `` instead of ``.
If you're a web developer eyeing your first React Native project and bracing for a total restart, don't — it's far more transfer than restart, once you know which parts are which. Tell me what your app needs to do on the phone and I'll tell you where your web instincts will help and where they'll trip you.
---
# React on the Desktop: When a Window Beats a Tab
Canonical: https://ma-x.im/blog/react-playbook-desktop
Author: Maksym Kuzmitskyi
Published: Jun 05, 2026
There's a specific moment where the desktop pitch becomes irresistible. You've built a genuinely good React app, it lives in a browser tab, and someone asks "can we make it a real app?" — with a dock icon, a name, a window of its own. And the answer is yes, easily, with the same React code you already have. Electron and Tauri will both wrap it into a program that installs like any native app. The demo takes an afternoon and feels like magic.
So the tempting question is "how do I turn my React app into a desktop app," and it's the wrong one to lead with. The right question — the one that actually determines whether this is worth doing and which tool to reach for — is *what do I gain by leaving the browser at all?* Because a desktop wrapper that just shows your website in a frameless window is a worse browser tab: heavier, harder to update, and offering the user nothing they didn't already have. The whole justification for going desktop is the stuff a browser tab structurally *cannot* do, and if you don't need that stuff, you probably shouldn't be here.
This article is about that line — what the desktop actually buys you — and the honest tradeoff between the two tools that get you there.
## What a Browser Tab Genuinely Can't Do
Start with the reason to leave the browser, because it's the whole point. A web page runs in a sandbox, deliberately walled off from the machine it's on — that's a security feature, not a limitation to complain about. But it means there are real capabilities a tab simply doesn't have, and those capabilities are your entire reason for going desktop.
Deep filesystem access — reading and writing arbitrary files on the user's disk, not the sandboxed trickle a browser allows. Real OS integration — a tray icon, native menus, global keyboard shortcuts that work when your app isn't focused, notifications that feel like the system's own. Talking to native or system-level resources the browser keeps off-limits. Working genuinely offline as a first-class program, not a web page hoping its service worker cached the right things. If your app needs one of these, the desktop isn't a nicety — it's the only place the feature can exist.
And the contrapositive matters just as much: if your app needs *none* of these — if it's fundamentally a web app that someone just wants to "feel" installed — then wrapping it in Electron mostly buys you weight and update headaches. Be honest about which side of that line you're on before you install anything. The desktop is for apps that need to touch the machine, not for apps that want a fancier bookmark.
## The Two Tools, and the Real Tradeoff
Assuming you genuinely need out of the browser, there are two serious choices, and they represent a real architectural fork — not a matter of taste.
**Electron** is the established one — VS Code, Slack, Discord are all Electron. Its model is straightforward: it ships an entire copy of Chromium *and* Node.js inside your app. Your React runs in a real Chrome, and you get full Node in the backend process, so everything you know works exactly as expected. The cost is equally straightforward: because every app bundles its own whole browser, a trivial Electron app starts at a hundred-plus megabytes and a chunk of memory before it does anything. You're shipping a browser per app, times every Electron app the user has installed.
**Tauri** is the modern challenger with a different bet. Instead of bundling Chromium, it uses the operating system's *own* built-in webview — the browser engine already on the machine. And instead of Node, its backend is Rust. The payoff is dramatic: Tauri apps are a fraction of the size and memory, often a few megabytes instead of a hundred. The cost is the two edges of that same bet. Using the OS webview means you're rendering on WebKit on macOS, WebView2 on Windows — *different engines* — so you inherit cross-browser inconsistency as a desktop concern, which is a genuinely strange thing to have to test for in an installed app. And the native backend is Rust, so any serious system-level logic pulls you into a language your React team may not know.
```
Electron Tauri
Renderer bundled Chromium (same OS webview (WebKit / WebView2,
everywhere) differs per platform)
Backend Node.js Rust
App size 100MB+ (ships a browser) a few MB (uses the OS's)
You trade size & memory cross-engine testing + Rust
```
So the choice isn't "which is better," it's which cost you'd rather pay. Electron trades disk and memory for total consistency and a stack your web team already knows. Tauri trades a small footprint for cross-engine testing and a Rust backend. Neither is wrong; they're priced differently, and the right pick depends on whether size or familiarity hurts you more.
## The Part That's Actually Different: Two Processes and a Bridge
Whichever you choose, there's one architectural shift that catches web developers off guard, and it's worth understanding because it shapes everything you build. A desktop app is not one environment — it's *two*, with a guarded door between them.
Your React UI runs in the renderer, which is still fundamentally a web context, sandboxed. The powerful stuff — filesystem, OS APIs, native calls — runs in a separate, privileged backend process (Node in Electron, Rust in Tauri). They can't just call each other's functions; they communicate over an explicit bridge, passing messages across. Your React code doesn't read a file directly — it *asks* the backend to, and the backend, which actually has the permission, does it and sends the result back.
```ts
// Renderer (your React UI): it cannot touch the disk itself.
// It asks the privileged backend to do it — Tauri example.
import { invoke } from '@tauri-apps/api/tauri';
async function loadNote(id: string) {
// Crosses the bridge to the Rust backend, which has real file access.
const contents = await invoke('read_note', { id });
return contents;
}
```
This should feel familiar, because it's the same pattern the whole series keeps circling: a sandboxed, untrusted frontend asking a privileged, trusted backend to do the dangerous thing — exactly like the [client/server split in auth](/blog/react-playbook-authentication), just moved onto one machine. The renderer is the browser; the backend process is your server; the bridge is the API between them. Treat that boundary with the same seriousness — validate what crosses it, expose only the specific operations you mean to — and a desktop app stops feeling exotic and starts feeling like a client/server app you happen to ship in one installer.
## How I'd Approach It
Strip it to decisions:
- **Ask what you gain, not whether you can.** If you don't need filesystem, OS integration, or true offline, the desktop is a heavier browser tab. Don't ship one for a fancy bookmark.
- **The desktop is for touching the machine.** Deep file access, tray/menus/global shortcuts, native resources, first-class offline — that's the whole reason to leave the browser.
- **Electron vs Tauri is a cost choice, not a quality one.** Electron: big and memory-hungry, but consistent and web-stack-familiar. Tauri: tiny, but cross-engine testing and a Rust backend.
- **It's two processes with a bridge.** Your React renderer asks a privileged backend to do the powerful things. Treat that bridge like a client/server boundary, because it is one.
The thing I want you to take from this is that "turn my React app into a desktop app" is the easy, uninteresting half. The wrapper is a solved afternoon. The real work — and the only justification for the extra weight and the two-process complexity — is the native power you reach for once you're out of the sandbox. Go desktop when your app needs the machine. Stay in the tab when it doesn't. And when you do go, remember you didn't escape the client/server split, you just packaged both halves into one window.
The next article stays off the web but changes machines entirely: [React Native and mobile](/blog/react-playbook-react-native) — where "same code, new platform" gets far more honest about what actually carries over and what doesn't.
If you're weighing a desktop build and can't tell whether you truly need to leave the browser, that's the exact question worth answering first — and it's usually clearer than it feels. Tell me what native capability you're reaching for and I'll tell you if the desktop is really the only place to get it.
---
# Documenting Components: The Only Docs That Don't Rot
Canonical: https://ma-x.im/blog/react-playbook-component-documentation
Author: Maksym Kuzmitskyi
Published: Jun 02, 2026
Every team I've watched try to document their components starts in the same place: a page in the wiki. Someone writes up the `Button` — here are the variants, here's a screenshot, here's a table of props — and for about three weeks it's great. Then someone adds a `loading` prop and doesn't update the page. Then the primary color changes and the screenshot is now a lie. A month in, the docs describe a component that no longer exists, and the whole team has quietly learned to not trust them. So they read the source instead, and the docs rot in place, occasionally misleading a new hire.
This isn't a discipline problem, and treating it as one — "we just need to be better about updating the docs" — is why it keeps happening. People aren't lazy; the docs are structurally doomed. The reason is simple and it's the whole point of this article: **the documentation lives in a different place than the code it describes.** Two sources of truth, updated by two separate acts of will, and one of them always falls behind. You've seen this exact shape before — it's the same two-sources-of-truth failure as the [real-time cache](/blog/react-playbook-websockets), just applied to prose instead of state.
So the question isn't "how do we write better component docs." It's "how do we make docs that *can't* drift" — and the answer is to stop writing docs that sit next to the code and start generating them from the code itself.
## Why the Wiki Always Loses
Sit with why the wiki page decays, because the mechanism matters. When you change a component, updating its separate documentation is a *second, optional action*. The code change ships value on its own; the doc update is extra work with no immediate payoff, easy to defer, easy to forget, and nothing breaks when you skip it. So under any deadline — which is always — the doc update is the first thing to go. Multiply that across a team and a year, and every hand-maintained doc trends toward wrong.
The insight that fixes it is to remove the second action entirely. If the documentation is *derived from the code* rather than maintained alongside it, then changing the code changes the docs, automatically, with no act of will required. The drift becomes impossible not because everyone got more disciplined, but because there's no longer a gap for drift to live in. This is the same instinct as generating types from a [schema](/blog/react-playbook-typescript-patterns) or [migrations from a model](/blog/react-playbook-database-turso): one source of truth, everything else derived. Documentation is just another thing that should be derived, not duplicated.
## The Props Table Should Come From the Props
The most concrete version of this: that table of props everyone hand-writes and forgets to update? It should not be hand-written. Your component's props are *already* fully described — in its TypeScript types. That's a machine-readable specification of every prop, its type, whether it's required, sitting right there in the code.
```tsx
interface ButtonProps {
/** Visual style of the button. */
variant: 'primary' | 'secondary' | 'danger';
/** Shows a spinner and disables interaction. */
loading?: boolean;
/** Called when the button is clicked. */
onClick: () => void;
}
export function Button({ variant, loading, onClick }: ButtonProps) {
/* ... */
}
```
Everything a props table would contain is in that interface — the names, the exact allowed values of `variant`, which props are optional, and even the descriptions in the doc comments. Tooling like [Storybook](https://storybook.js.org) reads those types directly and generates the props table for you. Add a prop, the table gains a row. Change `variant`'s options, the table updates. Delete a prop, its row disappears. You didn't maintain anything — the documentation is a *view* of the types, and the types can't be wrong because they're the code that actually runs. The single most rot-prone piece of component docs becomes the single most reliable one, purely by deriving it instead of writing it.
## Living Examples Beat Screenshots
The other half of component docs is showing the thing in use, and here the screenshot is the villain. A screenshot is a photograph of the component at one moment in the past — it stops being accurate the instant anything changes, and it can't show a single interactive state. Hover, focus, loading, disabled, the error variant — a static image shows none of it and silently goes stale on all of it.
The fix is the same move again: don't take a picture of the component, *render the real component*. A story in Storybook is a live instance of the actual component, mounted with real props, that you can interact with:
```tsx
import type { Meta, StoryObj } from '@storybook/react';
import { Button } from './Button';
const meta: Meta = { component: Button };
export default meta;
export const Primary: StoryObj = {
args: { variant: 'primary', onClick: () => {} },
};
export const Loading: StoryObj = {
args: { variant: 'primary', loading: true, onClick: () => {} },
};
```
Those aren't images of a button — they're the button, running, with the exact props your app would pass. If the button changes, the stories change with it, because they *are* the component, not a snapshot of it. You can hover the real hover state, watch the real spinner, tab to the real focus ring. A screenshot documents what the component looked like once; a story documents what the component *is* right now, and stays honest by construction.
And there's a compounding benefit that ties back to the [design conversation](/blog/react-playbook-design-prototyping): a living component catalog is where designers and engineers actually agree on what exists. When the real `Button`, in all its states, is browsable in one place, "does this already exist?" has an answer you can see and click — which is the difference between reusing the component and rebuilding it slightly differently for the fifth time.
## How I'd Approach It
Strip it to decisions:
- **Separate docs always rot.** It's not a discipline problem — it's two sources of truth. Stop maintaining docs next to the code.
- **Derive, don't duplicate.** Generate documentation from the code so changing the code changes the docs, automatically.
- **The props table comes from the types.** Your TypeScript interface already is the spec; let tooling render it. Never hand-write a props table.
- **Render real components, not screenshots.** A live story stays accurate and shows interactive states; an image is stale the moment you save it.
- **A living catalog drives reuse.** When every component is browsable in all its states, "does this exist?" becomes answerable — and things get reused instead of rebuilt.
The reason component docs have such a bad reputation is that almost everyone builds them to fail, then blames themselves when they do. A wiki page and a screenshot are drift waiting to happen, and no amount of resolve fixes a structural flaw. The shift that makes documentation actually last is to stop treating it as a thing you *write* and start treating it as a thing you *derive* — from the types, from the real components, from the code that's already the truth. Do that, and your docs stop being a chore you fall behind on and become a side effect of building the components at all. That's the only kind of documentation I've seen survive contact with a deadline.
This is where the "build a real app" spine of the series ends — from starting a project all the way through documenting what you built. The remaining articles step outside the browser entirely: next up, [React on the desktop](/blog/react-playbook-desktop) — when Electron or Tauri actually earns its place, and what changes when your React app is a window instead of a tab.
If your team has component docs that nobody trusts, it's almost certainly the separate-source-of-truth problem, and it's fixable without a documentation crusade. Tell me how your docs are set up and I'll tell you which piece to derive instead of write.
---
# Design Prototyping for React: Where the Architecture Actually Starts
Canonical: https://ma-x.im/blog/react-playbook-design-prototyping
Author: Maksym Kuzmitskyi
Published: May 29, 2026
The way most engineers relate to a design file is as a target to hit. The designer hands over a Figma frame, and the job — as everyone tacitly agrees — is to make the screen look like the picture. Pixel for pixel, color for color. Reproduce it, get it approved, move on.
I want to push on that framing, because I think it's the root of a lot of avoidable pain. A design isn't a picture you copy. It's the first draft of your component architecture, whether anyone treats it that way or not. The structure of that screen — what repeats, what nests, what varies, where the boundaries fall — *is* the structure of the code you're about to write. Which means the most consequential architectural decisions in a feature are often made in a design tool, by someone thinking about spacing and hierarchy, long before an engineer opens their editor. And when the design's structure and the code's structure disagree, you get the codebases everyone recognizes: technically matching the mockup, quietly miserable to maintain.
So this article is about reading a design the way it deserves to be read — as architecture — and why that shift changes both what you build and how you work with the people who design it.
## A Design Has Structure, Not Just Appearance
Look at any real screen and there are two different things present at once. There's the *appearance* — the colors, the fonts, the shadows, the exact pixels. And there's the *structure* — this card repeats six times, that button is the same button as the one on the other screen, this panel contains a header and a list, these three stats are the same shape with different data.
Reproducing appearance is the shallow job. Reading structure is the real one, because structure is what maps to components. When you see six cards, the architectural fact isn't "six cards" — it's "one `Card` component, rendered six times." When you see a button here that's clearly the same button as three other screens, the fact is "this is one shared `Button`, not a thing I restyle locally each time." The design is quietly telling you what your components are, what your reusable primitives are, and how they compose. A developer who only sees the picture reproduces the pixels and invents an ad-hoc structure underneath. A developer who reads the structure lets the design hand them their [component boundaries](/blog/react-playbook-code-structure) for free.
> A mockup shows you what the screen looks like. Read carefully, it also shows you what your components are, which ones repeat, and where they compose. The second reading is the one that keeps your codebase sane.
## Same Component, Different States — the Thing Static Mockups Hide
Here's where the "design is a picture" framing does the most damage, and it's the single most valuable thing to internalize about prototyping for React.
A static mockup shows you one moment. But a React component is never one moment — it's every state that data can put it in. The screen you were handed shows a list with eight items. Your component also has to handle: zero items (the empty state), one item, hundreds (does it scroll, paginate, virtualize?), the loading moment before any data arrives, and the error case when the fetch fails. The mockup showed you one of five or six realities, and if you only build the one you were shown, you'll ship a component that looks perfect in the demo and breaks the first time real data is empty or slow.
This is why the most useful thing you can do with a design *isn't* to start coding it — it's to interrogate it. Before writing the component, I go looking for the states the mockup didn't show. What does this look like with no data? While it's loading? When it fails? When the text is three times longer than the placeholder? When there are two hundred rows instead of eight? Half the time the honest answer is "the designer didn't think about that yet," and surfacing it *before* you build is enormously cheaper than discovering it in QA. The static frame is the happy path; your component is responsible for all the paths, and prototyping is where you find the missing ones.
## This Is a Conversation, Not a Handoff
That interrogation is exactly why I don't think of design-to-code as a handoff. A handoff is one-directional: design finishes, throws the result over a wall, engineering catches it. But the questions that matter — what are the empty and error states, is this really the same component as that one, does this pattern already exist in our system — can only be answered *together*, and answering them early is where the leverage is.
When engineering engages with design *during* prototyping instead of after, a few things change. Reusable pieces get spotted before they're built five slightly-different times. Missing states get designed instead of improvised by whichever developer hits them first. And the design starts to align with the components that already exist — which connects straight back to the [design systems](/blog/building-design-systems-that-scale) idea: a prototype built from the components you already have is a prototype that ships in a fraction of the time, because the answer to "how do I build this" is "you mostly already did." The handoff model forecloses all of that by making the conversation happen too late, after the structural decisions have already hardened on both sides.
I'm not arguing engineers should design. I'm arguing that the boundary between "design work" and "architecture work" is far blurrier than the org chart suggests, and pretending it's a clean line — a wall with a handoff over it — is how you get designs that fight the code and code that fights the design.
## How I'd Approach It
Strip it to decisions:
- **Read a design for structure, not just appearance.** What repeats, what nests, what varies — that's your component tree, handed to you.
- **A static mockup is one state.** Before coding, hunt for the ones it hides: empty, loading, error, overflow, huge data. Build all the realities, not the one you were shown.
- **Interrogate before you implement.** The cheapest place to discover a missing state is a design review, not QA.
- **Treat it as a conversation, not a handoff.** Engaging during prototyping surfaces reuse and missing states while they're still cheap to fix.
- **Prototype from your existing components.** A design aligned to the system you already have ships far faster than one drawn from scratch.
The reframe that changed how I work is small but load-bearing: the design tool is where architecture starts, not where it waits. The person arranging cards and spacing is making decisions about repetition, hierarchy, and composition — the exact decisions I'll be encoding in components an hour later. When I treat the mockup as a picture to copy, I throw all that structural information away and rebuild it, worse, in code. When I treat it as the first draft of the architecture, the design does half the hard thinking for me — and the half it left out becomes a conversation instead of a bug.
Next, the flip side of building components well: [documenting them](/blog/react-playbook-component-documentation) — so the reusable pieces you and your designers just agreed on actually get reused instead of quietly rebuilt for the fifth time.
If your team's design-to-code process feels like reproducing pictures and constantly rediscovering missing states in QA, that's the handoff model doing its usual damage. Tell me where it hurts — the reuse, the missing states, the drift — and I'll tell you where the conversation needs to move earlier.
---
# Sending Email from a React App: A Backend Problem in Disguise
Canonical: https://ma-x.im/blog/react-playbook-mails
Author: Maksym Kuzmitskyi
Published: May 26, 2026
"When someone signs up, just send them a welcome email." It's the kind of request that gets tossed into a standup like it's nothing, and the person saying it genuinely believes it's a five-minute task. Send an email. How hard could it be?
Here's the thing that makes email sneaky: the part you'd expect to be hard is trivial, and the part you'd expect to be trivial is where the whole thing lives. Triggering an email from your app is a single function call. *Actually getting that email into someone's inbox* — not their spam folder, not bounced, not silently dropped — is a genuinely deep backend problem involving deliverability, sender reputation, authentication protocols, and a rendering environment stuck two decades in the past. And almost none of it is a React problem, which is exactly why it catches frontend developers off guard.
So this article is a map of where the real work is. Because the most useful thing I can tell you about email in a React app is which parts to not do yourself, and why the boundary sits where it does.
## The Line: The Client Never Sends Email
Start with the hard boundary, because it's the one people are tempted to cross. **Your React app does not send email. Ever.** It triggers a request to your backend, and your backend sends the email.
This isn't a style preference, it's a security wall. Sending email requires credentials — API keys for your email service — and anything in your React bundle is public. Ship that key to the client and you've handed the entire internet the ability to send email *as you*, which means spammers now have a free megaphone wearing your domain's reputation. Within days your domain is blacklisted and even your legitimate mail stops arriving. So the flow is always the same shape as [payments](/blog/react-playbook-payments) and [auth](/blog/react-playbook-authentication): the client asks, the server acts, and the credential never leaves the server.
```ts
// The client's entire involvement: ask the backend to do it.
async function requestWelcomeEmail(userId: string) {
await fetch('/api/emails/welcome', {
method: 'POST',
body: JSON.stringify({ userId }),
});
}
```
That's the whole frontend story. There is no `sendEmail` in your components, no email API key in your environment variables with a public prefix, no SMTP in the browser. The moment email touches the client, you've done it wrong. Everything interesting from here happens on the server.
## Why You Don't Talk to SMTP Yourself
On the backend, the naive mental model is that you connect to a mail server over SMTP and send. You *can* do that. You shouldn't, and understanding why is the core of this whole topic.
Getting an email delivered is not about transmitting it — it's about being *trusted* enough that the receiving server puts it in the inbox instead of the spam folder or the trash. That trust is a system: your domain needs authentication records (SPF, DKIM, DMARC) that prove you're allowed to send as your domain; your sending IP needs a *reputation* built over time; you need to handle bounces and complaints so you stop mailing dead addresses; and you need to not trip the spam filters that treat unknown senders with suspicion. Running your own mail server means owning all of that — reputation, blacklist monitoring, authentication, the works — and it is a full-time infrastructure job that has nothing to do with your product.
This is why transactional email services — [Resend](https://resend.com), Postmark, SendGrid — exist, and why using one isn't laziness but the correct architecture. They've spent years building sender reputation, they handle the authentication protocols, they manage bounces and deliverability, and they give you a clean API. Your backend calls that API; the hard, invisible work of *actually getting delivered* is theirs.
```ts
// Your server. The service owns deliverability; you own intent.
import { Resend } from 'resend';
const resend = new Resend(process.env.RESEND_API_KEY); // server-only secret
app.post('/api/emails/welcome', async (req, res) => {
const user = await getUser(req.body.userId);
await resend.emails.send({
from: 'hello@yourdomain.com',
to: user.email,
subject: 'Welcome aboard',
react: , // more on this below
});
res.json({ queued: true });
});
```
Same lesson as every article in this series: the raw capability (SMTP) is a footgun, and the value is a service that owns the messy, reputation-dependent edges. You are buying deliverability, not a send button.
## The Genuinely Weird Part: Email Rendering Is Stuck in 2005
Here's the one place your React skills partly transfer, and it comes with a nasty surprise. You'd assume you can build an email template with normal components and modern CSS. You cannot, and this trips up every frontend developer exactly once.
Email clients — Outlook especially, but not only — render HTML with engines that are decades behind browsers. No flexbox, no grid, no modern CSS, inconsistent support for things you consider baseline. The reliable way to lay out an email is *tables*, the way the web worked in 2005, with inlined styles because `