DEV Community: Maksym Kuzmitskyi (MaximusFT)

Barrel Files: The Import You Love and the Bundle You Hate

Maksym Kuzmitskyi (MaximusFT) — Fri, 19 Jun 2026 00:00:00 +0000

There's a specific kind of import that feels like good engineering:

import { Button, Card, Modal, Tooltip } from '@/shared/ui';

One line. One path. Clean. Compare it to the honest version:

import { Button } from '@/shared/ui/Button';
import { Card } from '@/shared/ui/Card';
import { Modal } from '@/shared/ui/Modal';
import { Tooltip } from '@/shared/ui/Tooltip';

The first one looks like a tidy public API. The second looks like clutter. So of course teams reach for the first — they add an index.ts that re-exports everything, and the whole folder gets a single front door. That file is a barrel, and it's one of the most quietly expensive habits in a React codebase. Not because it's wrong. Because it's right just often enough that people stop questioning it.

I brought this up at the end of the shared/ article and promised to come back to it. Here's the come-back.

What a barrel actually is

A barrel is just a file — almost always index.ts — whose only job is to re-export other modules:

// shared/ui/index.ts
export { Button } from './Button';
export { Card } from './Card';
export { Modal } from './Modal';
export { Tooltip } from './Tooltip';

Now @/shared/ui resolves to this file, and consumers import named things from one place. The appeal is real: imports get shorter, the folder gets a defined surface, and you can move Button.tsx around internally without breaking any consumer, as long as the barrel keeps pointing at the right place. That last part — decoupling the internal file layout from the public import path — is a genuine architectural benefit, not just cosmetics. It's the same "public API of a folder" idea that makes feature boundaries work.

So far this sounds like something you'd want everywhere. That's exactly the trap.

The cost hides where you're not looking

Here's the problem. When you write import { Button } from '@/shared/ui', you are not importing Button. You are importing the barrel, and the barrel imports everything. Button, Card, Modal, Tooltip, and whatever those pull in — the whole folder loads to hand you one component.

"But tree-shaking removes the unused ones," you say. Sometimes. Tree-shaking is real, but it's fragile, and a barrel is exactly the shape that breaks it. All it takes is one module in the barrel with a side effect — a file that runs code at import time, registers something, mutates a global, or is marked as having side effects in package.json — and the bundler can no longer prove the other exports are safe to drop. To stay correct, it keeps them. Your one-line Button import just pulled in Modal, its focus-trap library, and the animation dependency Tooltip uses.

You won't see it in code review. The import line looks identical whether the tree shakes cleanly or not. You'll see it in a bundle analyzer six months later, staring at a route that weighs 400KB and wondering why a page with two buttons is importing a charting library. The answer is almost always a barrel somewhere in the chain, quietly gluing unrelated things together.

There's a second cost that shows up sooner: build and dev-server speed. Every barrel is a fan-out. Import one thing through @/shared/ui and the module graph has to resolve every file the barrel touches, and every file those touch. In a big app with barrels re-exporting barrels re-exporting barrels, you get a dependency graph that explodes on almost any import. Cold dev starts crawl. Hot updates touch more than they should. The tooling spends its time walking a graph you created for the sake of a shorter import line.

A barrel trades a real cost you can't see for a cosmetic benefit you can.

The worst offender: the app-wide barrel

The pattern that does the most damage is the ambition to have one barrel at a high level that re-exports a whole layer:

// features/index.ts — please don't
export * from './edit-policy';
export * from './create-claim';
export * from './billing-dashboard';
export * from './user-settings';
// ...twenty more

Now import { EditPolicyForm } from '@/features' reaches into a barrel that transitively imports every feature in the app. Import one feature and you've referenced all of them. Code-splitting — the entire point of which is that a route loads only what it needs — quietly stops working, because from the bundler's view everything is connected to everything through this one file. I've watched a lazy-loaded route pull in the whole app because a single import went through a top-level barrel instead of reaching for the specific module.

The export * form is especially nasty. It's not just eager; it forces the bundler to load a module just to find out what names it exports, so it can figure out which star-export a given name came from. Named re-exports (export { X } from './x') are at least explicit. export * is a blank check.

When a barrel earns its place

I'm not anti-barrel. I use them. The question is never "barrels: yes or no." It's "does this specific barrel pay for itself." A barrel earns its place when three things are true at once.

It wraps a genuine, stable public API. A design-system package where Button, Card, and Modal are the whole point and consumers legitimately pull from across it — that's a real interface, and a barrel is the right way to express it. The barrel isn't hiding a mess; it's naming a surface that was always meant to be used as a whole.

It's small and internally cohesive. A barrel over five related components in one feature is cheap — importing one probably means you're near the others anyway, and the fan-out is tiny. The cost of a barrel scales with what's behind it. Small folder, small cost.

Nothing behind it has surprising weight or side effects. Pure, light modules tree-shake fine through a barrel. The danger is heavy or effectful modules — a component that drags in a 200KB dependency, a file that runs setup at import. One of those behind a barrel poisons every import that passes through it.

Miss any of those and the barrel is working against you. A top-level @/features barrel fails all three: not a stable surface, not small, and full of heavy things. A shared/ui/index.ts over a real design system passes all three. Same mechanism, opposite verdict — which is the whole reason "always use barrels" and "never use barrels" are both wrong.

What I actually do

My rules are boring, which is how I like architecture rules.

Import from the specific file by default. import { Button } from '@/shared/ui/Button' is my normal. The import is three words longer and I never think about it again. No fan-out, no tree-shaking gamble, no accidental coupling.

// default: reach for the exact thing
import { Button } from '@/shared/ui/Button';
import { formatCurrency } from '@/shared/lib/money';

Add a barrel only at a real boundary I've decided to publish. A feature's public entry point, a design-system package's root — places where "this is the surface, use it as one" is a deliberate architectural statement, not a convenience. And when I do, I write explicit named re-exports, never export *:

// features/edit-policy/index.ts — a deliberate public surface
export { EditPolicyForm } from './ui/EditPolicyForm';
export { useEditPolicy } from './model/useEditPolicy';
// internal helpers are NOT re-exported — they stay private

That barrel is doing architectural work: it defines what the feature exposes and hides everything else, so the rest of the app can't reach into the feature's guts. That's a barrel as an encapsulation boundary, which is worth having. A barrel as a typing convenience usually isn't.

Never barrel a whole layer. No @/features, no @/entities mega-barrel. Layers are not modules; they're categories. Giving a category a single import door is how code-splitting dies.

Verify with the analyzer, not with faith. Tree-shaking is a claim, not a guarantee. Run a bundle analyzer, find the route that's too heavy, and trace it. More often than not the culprit is a barrel doing exactly what I described — and the fix is changing one import from the barrel to the specific file.

The real lesson isn't about barrels

Strip away the mechanics and this is the same idea as the shared/ article, pointed at a different symptom. A barrel is a public API for a folder. Public APIs are worth having when there's a real boundary to protect and a real surface to name. They're pure cost when you add them out of habit, to make imports prettier, over a pile of things that were never meant to be used as a unit.

So the question to ask isn't "should this folder have an index.ts." It's "does this folder have a public API worth defining — and am I willing to pay the fan-out to define it." When the answer is yes, barrel it, name the surface, and hide the rest. When the answer is "I just want shorter imports," reach for the specific file and move on. The prettier import was never worth the bundle you couldn't see.

Next in this stretch on architecture, I want to get at the thing underneath both of these articles: how modules should depend on each other at all — the direction of the arrows, who's allowed to import whom, and why a dependency graph is the most honest picture of your app's health. If you've got a bundle that mysteriously balloons on one route, open the analyzer and go hunting for a barrel — then tell me what you found. I'm always curious how far the fan-out reached.

The shared/ Folder Is Not a Place, It's a Promise

Maksym Kuzmitskyi (MaximusFT) — Tue, 16 Jun 2026 00:00:00 +0000

Open the shared/ folder in almost any React app that's been alive for a year. Count the files. Then try to explain, out loud, what the folder is for — not what's in it, what it's for. You'll stall. There's a date formatter, sure, and a Button. But there's also useUserPermissions, a formatPolicyNumber, half a checkout state machine, a legacyApiAdapter, and three hooks whose names start with use and end in a shrug.

That folder didn't get that way because someone was careless. It got that way because shared/ is the one folder in your app with no rule attached to it. Everything else has a reason to reject a file. shared/ accepts everything. And a folder that accepts everything isn't a category — it's a drain.

I already flagged this in the code structure article: shared/ is the most abused folder in React architecture. That piece told you the rule. This one is about why the rule is so hard to keep, and how to dig out once you've already lost.

Why the drawer fills up

The junk drawer isn't a discipline problem. If it were, telling people "be more careful about shared/" would fix it. It never does. The rot is structural, and it comes from three forces that all push the same direction.

The naming trap. You write a hook. Where does it go? If it has an obvious owner — features/edit-policy — the answer is easy. But a lot of code sits in the awkward middle: not clearly owned, not clearly generic. useDebouncedValue is generic. usePolicyDraftAutosave is owned. But useAutosave, the one that started generic and quietly grew a policyId parameter — that one has no obvious home. So it goes to shared/, because shared/ never says no.

The reuse reflex. The moment a second file wants something, the instinct is to "lift it up" so both can reach it. This feels like good engineering. It's usually premature. Two components in the same feature using one helper is not a reason to move that helper three layers up into shared/lib — it's a reason to keep it inside the feature. Reuse across a boundary is a real signal. Reuse within a boundary is just normal code living near the thing that uses it.

The path of least resistance. shared/ is at the bottom of the dependency graph, so everything can import from it. That makes it the safest place to drop something when you're in a hurry and don't want to think about ownership. No import will ever break. And that's exactly the problem: the folder that's safe to import from is also the folder that's frictionless to dump into.

Put those three together and you don't get a junk drawer because people are bad at their jobs. You get one because the folder is doing precisely what an unconstrained folder does under pressure. Delivery pressure always wins over categorization, and shared/ is where "I'll sort it later" goes to never be sorted.

shared/ is not a place you put things. It's a promise you make about them.

That reframing is the whole article. The promise is: this code is domain-agnostic and portable — it would make sense in a completely different product. Every file in shared/ is you signing that promise. The drawer fills up because people put things there without noticing they're signing anything.

The test that actually works

The rule I gave in the structure article still holds, and it's the only test I've found that survives contact with a real team:

A file belongs in shared/ only if you could move it to a different product at the same company and it would still make sense.

A Button? Moves fine. A formatCurrency? Moves fine. An http client with your auth interceptor? Borderline — it moves if the auth scheme is company-wide, stays if it's app-specific. A useUserPermissions hook that knows your permission strings? Doesn't move. It's dressed up as generic — it takes a permission key, it returns a boolean, it looks reusable — but it's welded to your domain's idea of what a permission is. That's not shared code. That's domain code wearing a generic costume.

Here's the tell, in code. This looks shared:

// shared/hooks/usePermission.ts
export function usePermission(key: string): boolean {
  const { permissions } = useCurrentUser();
  return permissions.includes(key);
}

It isn't. useCurrentUser is a domain concept. The moment this hook reaches sideways into entities/user, it stopped being portable — it now depends on your app's notion of a user. Move it to a different product and it breaks. It belongs in entities/user, exported as part of that entity's public surface. What's left in shared/ should be the genuinely dumb primitive:

// shared/lib/includes.ts — portable, knows nothing
export const hasKey = (keys: string[], key: string) => keys.includes(key);

The portability test isn't about whether code can be reused. Almost anything can be reused if you squint. It's about whether the code knows about your domain. Knowledge is the boundary, not usage.

Make the boundary a wall, not a suggestion

A rule that lives only in a code review is a rule you will lose. Reviewers get tired. New people don't know it. The pressure that fills the drawer doesn't take weekends off. So the direction of dependencies — lower layers never importing from higher ones — has to be enforced by tooling, not vigilance.

ESLint's no-restricted-imports gets you most of the way with zero extra dependencies:

// eslint.config.js
export default [
  {
    files: ['src/shared/**'],
    rules: {
      'no-restricted-imports': [
        'error',
        {
          patterns: [
            {
              group: [
                '@/features/*',
                '@/entities/*',
                '@/widgets/*',
                '@/pages/*',
                '@/app/*',
              ],
              message:
                'shared/ must not import from higher layers. If this file needs domain code, it does not belong in shared/.',
            },
          ],
        },
      ],
    },
  },
];

Now the usePermission example from earlier fails the build the instant it imports useCurrentUser. The error message isn't just "no" — it explains the promise: if this file needs domain code, it doesn't belong here. The lint rule becomes the reviewer who never gets tired and never forgets the rule. For richer needs — enforcing that features can't import each other, that entities stay isolated — a dedicated boundaries plugin does the same job with more expressive rules, but the built-in gets a small team surprisingly far.

The point isn't the exact config. It's that the promise stops depending on everyone remembering it. You made shared/ say no. That single change is the difference between a folder that stays small and one that quietly triples every quarter.

Digging out of one you already have

Prevention is easy to talk about when the drawer is empty. Most of the time it isn't. You've inherited forty files and a folder that's load-bearing in ways nobody documented. You can't stop shipping features to go on an architecture retreat, and a big-bang "fix shared/" pull request is a merge-conflict machine that reviewers will rubber-stamp out of exhaustion. So don't do that. Dig out incrementally.

First, audit without moving anything. Go through shared/ file by file and tag each one with a comment — three buckets only:

Portable — passes the test. Leave it. This is what shared/ is for, and seeing what legitimately qualifies is calming.
Owned — knows about a domain concept. It has a real home in an entity or a feature; it's just sitting in the wrong place.
Split — genuinely two things fused together: a portable core with a domain-specific wrapper grown around it. The useAutosave-that-grew-a-policyId case.

Then move the easy ones. The Owned bucket is pure relocation — cut the file, paste it into its real home, fix the imports, done. Your lint rule from the previous section will actually help here: as you move domain code out, anything still illegally reaching into higher layers lights up red, showing you the next thing to fix. The compiler turns into a to-do list.

Then split the hard ones. For each Split file, separate the portable core from the domain wrapper. The core stays in shared/ as a dumb primitive. The wrapper moves down to the feature that needs the domain-specific behavior:

// before — one file in shared/, quietly domain-aware
// shared/hooks/useAutosave.ts
export function useAutosave(policyId: string, draft: PolicyDraft) { /* ... */ }

// after — the portable half
// shared/lib/useAutosave.ts — generic, no domain knowledge
export function useAutosave<T>(key: string, value: T, save: (v: T) => Promise<void>) { /* ... */ }

// after — the domain half, where it belongs
// features/edit-policy/model/usePolicyAutosave.ts
export function usePolicyAutosave(policyId: string, draft: PolicyDraft) {
  return useAutosave(`policy:${policyId}`, draft, savePolicyDraft);
}

Notice the generic useAutosave got better by being forced portable — it now takes its save function as an argument instead of hard-coding savePolicyDraft, which makes it genuinely reusable for the first time. Enforcing the boundary didn't just tidy the folder. It improved the primitive.

Then delete. The satisfying part. Once the Owned and Split files are gone, you'll almost always find a handful of files nothing imports anymore — helpers that existed only to serve code that moved. Delete them. A shrinking shared/ is the clearest signal the dig-out is working.

You don't have to finish in one sitting. Do a bucket a week. The direction matters more than the speed: as long as shared/ is getting smaller and more portable over time instead of larger and vaguer, you're winning.

A word on the barrel

While you're in here, you'll be tempted to add an index.ts that re-exports everything so imports look clean: import { Button, formatCurrency } from '@/shared'. Resist making that reflexive. A barrel over a genuinely small, stable, portable shared/ is fine. A barrel over the junk drawer just gives the junk drawer a tidy front door — and it can quietly drag your whole shared/ tree into every bundle that touches one export. The clean import is cosmetic; the coupling underneath is real. Fix the contents first. The public API of a folder is only worth having once the folder actually keeps a promise. That trade-off — barrels, bundles, and what a folder's public surface should really be — is a whole topic on its own, and one I want to come back to.

The folder was never the problem

It's easy to read all this as "shared/ is bad, avoid it." That's the wrong lesson. Every non-trivial app needs a home for genuinely portable code, and shared/ is a perfectly good name for it. The folder was never the enemy.

The missing promise was. A junk drawer is just a drawer that nobody agreed on the contents of. The fix isn't a better folder name or a stricter reviewer — it's making the promise explicit, and then making a machine enforce it so the promise survives the next deadline. Do that, and shared/ stops being the place your architecture goes to die and goes back to being the boring, dependable bottom of the stack. Boring is the goal. In shared/, boring is the whole point.

Next, I want to pick up the barrel thread I brushed past earlier: why the tidy index.ts that gives a folder a clean front door can quietly drag half your app into a bundle that only needed one function — and when it's still worth it.

If you've got a shared/ folder you're a little afraid to open — or a war story about one that got completely out of hand — I'd genuinely like to hear it. Reach out; I collect these.

React in 3D: When
Becomes

Maksym Kuzmitskyi (MaximusFT) — Fri, 12 Jun 2026 00:00:00 +0000

Becomes " width="800" height="420">

The first time someone tells you that you can build a 3D scene — a rotating model, a lit environment, a VR world — using React, it sounds like a category error. React is for interfaces. Buttons, forms, lists. Three-dimensional graphics are a different universe with their own math, their own pipeline, their own everything. Surely gluing them together is a hack.

It isn't, and the reason it isn't is the perfect note to end this series on. Because after twenty-nine articles about data fetching and forms and auth and desktop and mobile, the thing rendering React in 3D quietly proves is the idea that was underneath all of it the whole time: React was never really about the DOM. React is a system for describing a UI as a function of state and letting a renderer figure out how to make it real. The DOM was just the first and most common target. Point that same system at a 3D scene graph and it works — not as a trick, but because 3D was always within the reach of what React actually is.

So this last article is short, and it's really about a realization more than a technology. Let me show you what I mean.

The Scene Graph Is Just Another Tree

Here's the conceptual key. React renders trees. The DOM is a tree of elements — a div containing a span containing text. A 3D scene is also a tree: a scene contains a mesh, a mesh has a geometry and a material, lights and cameras sit alongside them. Same fundamental shape — a nested hierarchy of things — which means React's component model, built for exactly that shape, fits a 3D scene as naturally as it fits a webpage.

React Three Fiber is the renderer that makes this literal. It's React — real React, same hooks, same state, same composition — where the elements are 3D objects instead of HTML tags. You don't write <div>; you write <mesh>. You don't nest <p> inside <section>; you nest a geometry and a material inside a mesh.

import { Canvas } from '@react-three/fiber';

function Box() {
  return (
    <mesh rotation={[0.4, 0.2, 0]}>
      <boxGeometry args={[1, 1, 1]} />
      <meshStandardMaterial color="#22c55e" />
    </mesh>
  );
}

export function Scene() {
  return (
    <Canvas>
      <ambientLight />
      <pointLight position={[10, 10, 10]} />
      <Box />
    </Canvas>
  );
}

Read that and the uncanny thing is how ordinary it is. It's components. <Box /> 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. <mesh> is to a 3D renderer what <div> 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 to native phone. 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 <div> becomes <mesh> 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. <mesh> is the new <div>.
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

Maksym Kuzmitskyi (MaximusFT) — Tue, 09 Jun 2026 00:00:00 +0000

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 <div> 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 <div> and <span> and <p>, because those are HTML and there's no HTML here. You write <View> and <Text>, which map to genuine native components:

import { View, Text, Pressable } from 'react-native';

export function Greeting({ name }: { name: string }) {
  return (
    <View style={styles.card}>
      <Text style={styles.title}>Hi {name}</Text>
      <Pressable onPress={() => console.log('tapped')}>
        <Text>Tap me</Text>
      </Pressable>
    </View>
  );
}

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.

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. 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: 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 — where the same component model gets pointed at three-dimensional space, and what it means to write <mesh> instead of <div>.

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

Maksym Kuzmitskyi (MaximusFT) — Fri, 05 Jun 2026 00:00:00 +0000

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.

// 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<string>('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, 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 — 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

Maksym Kuzmitskyi (MaximusFT) — Tue, 02 Jun 2026 00:00:00 +0000

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, 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 or migrations from a model: 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.

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 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:

import type { Meta, StoryObj } from '@storybook/react';
import { Button } from './Button';

const meta: Meta<typeof Button> = { component: Button };
export default meta;

export const Primary: StoryObj<typeof Button> = {
  args: { variant: 'primary', onClick: () => {} },
};

export const Loading: StoryObj<typeof Button> = {
  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: 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 — 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

Maksym Kuzmitskyi (MaximusFT) — Fri, 29 May 2026 00:00:00 +0000

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 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 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 — 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

Maksym Kuzmitskyi (MaximusFT) — Tue, 26 May 2026 00:00:00 +0000

"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 and auth: the client asks, the server acts, and the credential never leaves the server.

// 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, 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.

// 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: <WelcomeEmail name={user.name} />, // 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 <style> blocks get stripped. Hand-writing that is miserable and easy to get wrong across the dozens of clients your users actually use.

The modern rescue is that you can write email templates as React components — using a library like React Email — and it compiles them down to the table-based, inline-styled HTML that survives Outlook. You get to think in components; the library deals with the 2005 rendering reality underneath.

import { Html, Button, Text } from '@react-email/components';

export function WelcomeEmail({ name }: { name: string }) {
  return (
    <Html>
      <Text>Hi {name}, glad you're here.</Text>
      <Button href="https://yourdomain.com/start">Get started</Button>
    </Html>
  );
}

That looks like a normal component, but <Button> and <Text> aren't rendering <button> and <p> — they emit the gnarly, table-wrapped, inline-styled markup that renders consistently from Gmail to a decade-old Outlook. It's the same pattern once more: a library absorbing an ugly reality so you can work in a sane abstraction. You write React; it ships something that would make you cry if you had to write it by hand.

How I'd Approach It

Strip it to decisions:

The client never sends email. It asks the backend. The API key is a server-only secret — leaking it burns your domain's reputation.
Don't run your own mail server. Deliverability is a reputation-and-authentication system, not a transmission problem. Use a transactional email service.
You're buying deliverability, not a send button. SPF/DKIM/DMARC, bounce handling, and IP reputation are the actual product these services sell.
Email rendering is stuck in the past. Write templates as React components via React Email; let it compile down to the table-based HTML that survives Outlook.

The reason "just send an email" turns into a week is that the sentence hides the entire iceberg. The tip — trigger a send — is the trivial thing everyone pictures. The mass underneath is deliverability, authentication, reputation, and a rendering environment that predates most of the developers working on it. The good news is that the whole iceberg is a solved, buyable problem: a transactional service for delivery, React Email for templates, and a hard rule that none of it touches the client. Get the boundary right and email goes back to being the five-minute task everyone assumed it was — because someone else already did the hard 95%.

Next, the series shifts from wiring things up to thinking about them differently: design prototyping for React — where design work stops being visual and starts being architectural, and why that handoff matters more than people admit.

If you've got emails landing in spam, or a template that looks perfect everywhere except Outlook, those are the two classic email potholes — deliverability and rendering — and both have known fixes. Tell me which one's biting you and I'll point you at the layer to check.

File Upload in React: The Input Is Easy, the File Is Not

Maksym Kuzmitskyi (MaximusFT) — Fri, 22 May 2026 00:00:00 +0000

Adding a file upload feels like a solved problem. You drop an <input type="file"> on the page, grab the file in an onChange, POST it to an endpoint. Ten minutes of work, and on your machine — with a 40KB avatar and localhost — it works flawlessly. You move on.

Then it meets reality. Someone uploads a two-gigabyte video from hotel wifi. Someone's connection drops at 90%. Someone picks a 500MB file and your server, which happily buffered the 40KB avatar into memory, tries to do the same with half a gigabyte and falls over. The file input was never the hard part. The hard part is that a file is a large, unreliable stream of bytes that has to travel from an untrusted browser, across a flaky network, to somewhere it can actually live — and every one of those words is a problem.

So this article isn't about the input element. It's about the thing underneath: moving real files, at real sizes, over real networks, without melting your server or lying to your user about what's happening.

The First Decision: Your Server Shouldn't Touch the File

Here's the instinct that causes most upload pain: the file goes browser → your server → storage. Your React app POSTs to your API, your API receives the bytes and forwards them to S3 or wherever. It's the obvious shape, and it's the wrong one for anything but tiny files.

Why it's wrong: your server now has to hold the file — in memory or on disk — while it passes through. A handful of users uploading large files at once and your server is doing nothing but shuttling bytes, burning memory and connection time on work that isn't yours. You've turned your application server into a file relay, and file relays are exactly what dedicated storage services already are, better than you.

The pattern that fixes it is presigned uploads , and it's worth understanding because it reshapes the whole flow. The file goes browser → storage directly, and your server's only job is to hand out permission. The client asks your API "I want to upload this file," your API asks the storage service for a short-lived, single-purpose URL, and hands that URL back. The browser then uploads straight to storage. Your bytes never touch your server.

// Your server: it never sees the file. It only grants permission.
app.post('/api/uploads/sign', async (req, res) => {
  const { filename, contentType } = req.body;

  // Ask storage for a short-lived URL scoped to this one upload.
  const uploadUrl = await storage.createPresignedUrl({
    key: `uploads/${crypto.randomUUID()}/${filename}`,
    contentType,
    expiresIn: 60, // seconds — the URL is useless after that
  });

  res.json({ uploadUrl });
});


// The browser: uploads the bytes directly to storage, not to you.
async function uploadFile(file: File) {
  const { uploadUrl } = await fetch('/api/uploads/sign', {
    method: 'POST',
    body: JSON.stringify({ filename: file.name, contentType: file.type }),
  }).then((r) => r.json());

  await fetch(uploadUrl, { method: 'PUT', body: file }); // straight to storage
}

Look at how the responsibilities split. Your server does a tiny, fast, cheap thing — validate the request, mint a scoped URL, respond. The multi-gigabyte transfer happens between the browser and a service built for exactly that. This is the same server-is-the-authority, client-does-the-work split from the auth and payments articles: your backend controls permission, but it doesn't do the heavy lifting it has no business doing.

The Second Reality: The Upload Is a Process, Not a Request

Once the file is going straight to storage, the next thing to accept is that a large upload is not an event that happens — it's a process that unfolds over time, and your UI has to treat it that way.

A 40KB avatar uploads instantly, so you can pretend it's a normal request. A 500MB file takes a minute or more, and during that minute the user is staring at your interface wondering if it's working. If you show them a frozen spinner, they'll assume it hung and refresh — killing the upload. So progress isn't a nice-to-have here; it's the difference between a feature that works and one users abort halfway. You have to report how far along the bytes are:

function uploadWithProgress(url: string, file: File, onProgress: (pct: number) => void) {
  const xhr = new XMLHttpRequest();
  xhr.upload.addEventListener('progress', (e) => {
    if (e.lengthComputable) onProgress(Math.round((e.loaded / e.total) * 100));
  });
  xhr.open('PUT', url);
  xhr.send(file);
}

That xhr.upload.progress event — one of the few times raw XMLHttpRequest still earns its place over fetch, which can't report upload progress — is what lets you draw a real progress bar. And a real progress bar changes user behavior: people wait for a bar that moves, and they abandon a spinner that doesn't. The technical work of measuring progress is small; the UX consequence of showing it is large.

The Third Reality: Big Files Need to Survive a Dropped Connection

Now the hardest layer, and the one that separates a toy from a product: what happens at 90% when the wifi blinks?

With a single PUT of the whole file, the answer is brutal — the upload fails and starts over from zero. For a 40KB file, who cares. For a 2GB file on a shaky connection, "start over from zero" may mean it never completes, because the odds of an uninterrupted multi-gigabyte transfer on bad wifi are genuinely low. The single-request model has a size ceiling baked in, and above it, uploads just don't finish.

The answer is chunked (multipart) uploads: split the file into pieces, upload each piece independently, and reassemble them in storage. Now a dropped connection costs you one chunk, not the whole file — you retry that chunk and continue. Uploads become resumable, and the size ceiling effectively disappears.

I want to be honest about the tradeoff, because this is where the "it's just an input" fantasy fully dies: chunking is genuinely more complex. You're tracking which chunks succeeded, retrying the ones that didn't, handling out-of-order completion, and telling storage to stitch them back together. This is real coordination logic, and it's exactly why you don't hand-roll it. Storage services expose multipart upload APIs, and libraries like Uppy wrap the whole thing — chunking, retries, progress, resumability — behind a component. The same lesson as every article in this series: the raw capability is a footgun, and the value is a library that owns the messy edges so you spend your attention on your product, not on retry bookkeeping.

Don't Forget: The File Is Untrusted

One security note that's too important to skip, because uploads are a classic attack surface. A file arriving from a browser is user input, and the same rule from the payments and auth articles applies: never trust it.

The client can claim a file is a 2MB image and actually send a 2GB executable. It can lie about the content type. So validation belongs on the boundary you control — size limits, allowed types, and ideally scanning — enforced when you mint the presigned URL and verified again on the storage side, never solely in the browser where a hostile user can bypass it. Client-side checks are for UX (tell the user "that's too big" before they wait); server-side checks are for safety. You need both, and you must never mistake the first for the second.

How I'd Approach It

Strip it to decisions:

Your server hands out permission, not bytes. Use presigned URLs so the file goes browser → storage directly. Don't turn your API into a file relay.
Treat the upload as a process. Show real progress from xhr.upload. A moving bar is why users wait instead of refreshing.
Chunk large files. Multipart uploads make transfers resumable and remove the size ceiling. Don't hand-roll it — use the storage API via a library.
The file is untrusted input. Validate size and type on the server boundary, not just in the browser. Client checks are UX; server checks are security.

The reason file upload is a rite of passage is that the easy version and the real version look identical right up until the file gets big or the network gets bad. The input, the POST, the success toast — all of that is the 10% you can write in your sleep. The 90% is respecting that you're moving a large, untrusted, interruptible thing across a connection you don't control, to a service that should be doing the heavy carrying instead of your server. Get that shape right — permission from your backend, bytes to real storage, progress and resumability for the user — and uploads stop being the feature that falls over in production.

Next, another piece of infrastructure that looks trivial and isn't: sending email from a React app — why "just send an email" is a backend problem wearing a frontend costume, and where the real work hides.

If you've got an upload that works for small files and dies on big ones, that's the single-request ceiling, and it's the most common upload bug there is. Tell me where it breaks — the server memory, the timeout, the 90% drop — and I'll tell you which layer is missing.

Time in React: The Bugs That Only Show Up at 2 AM

Maksym Kuzmitskyi (MaximusFT) — Tue, 19 May 2026 00:00:00 +0000

A date is just a value. It sits there in your data looking as harmless as a string or a number, and for a while it behaves. Then one day a user in another timezone reports that their meeting shows an hour off, or a "created today" badge appears on something made yesterday, or a date field creeps backward by one day every single time someone saves the form. Suddenly the most boring data type in your app is the source of the weirdest bug in your tracker.

Time is deceptive because it looks simple and is not. The complexity is real and mostly invisible on the machine you develop on, because your machine has one timezone, and so the entire category of problems — timezones, daylight saving, what "midnight" even means — stays hidden until someone in a different part of the world hits it. And they always hit it, usually in production, usually at an hour that makes the bug's name feel personal.

So this article is about the small number of ideas that keep time from breaking a React app. Not a date-library tour — a way of thinking about time that makes the whole class of bugs stop happening.

The One Rule That Prevents Most of It

If you take nothing else from this: store and transmit time in UTC. Convert to the user's local timezone only for display. That's it. That single discipline, applied without exception, eliminates the majority of time bugs before they can form.

A timestamp is a fact — the exact instant something happened. A timezone is a lens for viewing that fact. Store the fact once, in UTC. Choose the lens at the last possible moment, at render.

Here's why this works. An instant in time is absolute — the moment a user clicked "submit" is the same moment everywhere on Earth. What differs is how you describe it: 3 PM in London, 10 AM in New York, same instant. The bug factory is storing or comparing times in local terms, because then "the same moment" has many different labels and they drift against each other. Store the absolute fact in UTC, keep it in UTC through your database and your API, and only bend it into a human's local timezone when you're about to show it to that specific human. Timezone becomes a display concern, which is the only place it belongs.

The mirror-image mistake — the one that produces the "date shifts by a day every save" bug — is round-tripping a date through local time on the way in and out, so each save nudges it by the offset. Keep the storage UTC and the conversion display-only, and that whole genre of bug can't happen.

Why `new Date()` Keeps Betraying You

The native Date object is where good intentions go to die, and it's worth being specific about why, because the failure is silent.

Date is implicitly local. The moment you parse or construct one, it quietly adopts the runtime's timezone — which is your laptop in development and the user's machine (or worse, a server in yet another zone) in production. So code that looks correct on your screen produces different results for different users, and you won't see it, because your machine only ever shows you your own timezone's answer.

// Looks innocent. Behaves differently depending on where it runs.
const d = new Date('2026-07-21'); // midnight UTC... interpreted as LOCAL
d.getDate(); // 21 in London. 20 in New York. Same code, different day.

That getDate() returning 20 for a New York user is the entire "off by one day" bug in miniature — the string is midnight UTC, but Date shows it through local eyes, and New York's local eyes are still on the 20th. Nothing threw an error. The value is just wrong, for some people, some of the time, which is the worst kind of wrong.

Reach for a Real Library — and Watch Temporal

Because Date is a minefield, the long-standing answer is a library that makes timezone handling explicit instead of implicit. date-fns is my usual pick — modular, tree-shakeable, and its companion date-fns-tz makes conversions something you state rather than something that happens to you:

import { formatInTimeZone } from 'date-fns-tz';

// The instant is stored in UTC. Display it in the user's zone, explicitly.
const utcInstant = '2026-07-21T23:30:00Z';
formatInTimeZone(utcInstant, 'America/New_York', 'yyyy-MM-dd HH:mm'); // "2026-07-21 19:30"
formatInTimeZone(utcInstant, 'Asia/Tokyo', 'yyyy-MM-dd HH:mm'); // "2026-07-22 08:30"

Notice the same UTC instant renders as the 21st in New York and the 22nd in Tokyo — correctly, because the conversion is explicit and timezone-aware, not left to whatever Date guesses. You're stating the lens instead of inheriting it.

The genuinely good news is that the language itself is fixing this. Temporal — the new built-in date/time API — is designed specifically to end the Date era: immutable objects, explicit timezone handling, no more implicit-local footguns. It's landing in engines now, and it's the direction everything moves. If you're starting fresh, it's worth watching closely and reaching for as it stabilizes; it makes the "be explicit about timezones" discipline the default instead of something you bolt on with a library.

The Traps That Remain

Even with the UTC rule and a real library, a few sharp edges stay sharp, and they're worth naming because each has bitten real apps.

Daylight saving time means some days don't have 24 hours and some local times don't exist at all — the clock jumps forward and 2:30 AM simply never happened on that date. Any code doing time math by adding 24 * 60 * 60 * 1000 milliseconds and calling it "a day" is wrong twice a year; a real library that adds calendar days handles it, hand-rolled arithmetic does not.

"Midnight" and "today" are not absolute either — they're timezone-bound. "Show me everything from today" means a different range of instants for a user in Los Angeles than one in Berlin, and if your backend computes "today" in the server's timezone, half your users see the wrong day's data. "Today" is always someone's today, and you have to decide whose.

And serialization is where discipline leaks: the safe way to put a date on the wire is ISO 8601 in UTC (that trailing Z), because it's unambiguous. A date formatted for humans — or worse, a bare new Date().toString() — is a guessing game for whatever parses it next. Keep the API boundary UTC and ISO, and convert to human-readable strictly at the edges, at display.

How I'd Approach It

Strip it to decisions:

Store and send UTC. Convert only for display. The single rule that prevents most time bugs.
Distrust new Date(). It's implicitly local, so it's implicitly wrong for someone. Don't do timezone logic with it.
Use a real library (date-fns today) and make conversions explicit. Watch Temporal and adopt it as it lands.
Respect DST and "today." A day isn't always 24 hours, and "today" is always somebody's local today.
Serialize as ISO 8601 UTC. Unambiguous on the wire; humanize only at the edge.

The reason time bugs are so embarrassing is that they're invisible right up until they're not. Everything works on your machine, in your timezone, during the months without a DST transition — and then a user in Tokyo, or a clock change in November, or a "today" filter computed in the wrong zone quietly serves the wrong answer, and it looks like the code was never tested. It was tested. It was just tested in one timezone. Treating time as an absolute UTC fact that you view through a local lens only at the very end is the habit that makes those 2 AM bugs stop being yours.

Next, a different kind of unglamorous-but-treacherous: file uploads in React — progress, chunking, and the surprisingly deep problem of moving a large file from a browser to somewhere it can live.

If you've got a date that shifts by a day, a badge that says "today" when it isn't, or a meeting an hour off for some users, that's almost always a UTC-vs-local leak. Tell me where the wrong value shows up and I'll tell you which conversion is doing it.

Payments in React: The Client Never Decides You Got Paid

Maksym Kuzmitskyi (MaximusFT) — Fri, 15 May 2026 00:00:00 +0000

On the surface, taking a payment looks like the most ordinary thing in the world: a form with some fields, a submit button, a success message. You've built a hundred forms. This is just a form where one of the fields happens to be a card number.

It is not just a form, and the card number is exactly why. That field is radioactive. The moment a real card number touches your servers, you've walked into PCI compliance — a wall of security obligations that exists for very good reasons and that you do not want to be responsible for. And the "success message" hides the second trap: unlike every other form you've built, you don't actually know the outcome when the user clicks submit. The payment confirms asynchronously, somewhere you can't see, and the single most expensive mistake in this entire domain is letting your React app believe it got paid because a client-side callback said so.

So this article isn't a Stripe tutorial. It's about the two lines that matter — the one that keeps the card number away from you, and the one that decides where "you got paid" is actually true — because getting those two lines right is the whole job, and getting either wrong is how you end up either liable or robbed.

The First Line: Never Touch the Card Number

Start with the rule that shapes everything else: the raw card number must never reach your server. Not to "just pass it through," not to log it, not for a millisecond. The instant it does, you're in PCI-compliance scope, and that is a burden measured in audits and dread, not code.

The whole architecture of a modern payments provider exists to keep you out of that scope, and the mechanism is worth understanding because it's genuinely clever. You don't build the card input. Stripe does — via Stripe Elements, an iframe-based field that Stripe hosts and controls. The card number is typed into their iframe, on your page, and it goes straight to Stripe. Your JavaScript can't read it. Your server never sees it. What you get back instead is a token — a harmless reference that means "Stripe is holding a card for you" — and that is what flows through your system.

import { PaymentElement, useStripe, useElements } from '@stripe/react-stripe-js';

export function CheckoutForm() {
  const stripe = useStripe();
  const elements = useElements();

  async function handleSubmit(e: React.FormEvent) {
    e.preventDefault();
    if (!stripe || !elements) return;

    // Stripe collects the card in its own iframe and confirms directly.
    // The card number never touches your JS or your server.
    const { error } = await stripe.confirmPayment({
      elements,
      confirmParams: { return_url: 'https://example.com/order/complete' },
    });

    if (error) {
      // Show the user the reason. This is the "did it start" answer,
      // NOT the "did it succeed" answer.
    }
  }

  return (
    <form onSubmit={handleSubmit}>
      <PaymentElement />
      <button type="submit">Pay</button>
    </form>
  );
}

Look at what your code never handles: the card number itself. <PaymentElement /> is Stripe's iframe living inside your form. You render it, you style around it, and you stay completely out of scope for the one piece of data that would otherwise make you liable. This is the buy-don't-build principle from the auth article at its most extreme — the risk here is so high that building it yourself isn't a trade-off, it's a mistake.

The Second Line: The Client Doesn't Decide

Now the subtler and more dangerous part. The payment is initiated in the browser, but the browser is the last place that should decide whether it succeeded.

Here's why this bites people. The naive flow: user pays, Stripe's client call resolves, you show "Payment successful!" and mark the order as paid in your UI. It demos perfectly. And it's exploitable and unreliable, because the client is an environment you don't control. The user closes the tab the instant before the callback fires — the card was charged, your app never knew. The network drops after the charge but before the response — same. And a hostile user can straight up call your "mark as paid" endpoint without paying at all, because anything the client asserts, a client can fake.

The answer is the one that runs through this whole series: the client is untrusted; the server is the source of truth. The real confirmation doesn't come from your React callback. It comes from Stripe, server-to-server, via a webhook — Stripe calls your backend to say "this payment actually succeeded," and that server-side event is the only thing allowed to mark an order as paid.

// On your server — the ONLY place an order becomes "paid".
app.post('/webhooks/stripe', async (req, res) => {
  const event = stripe.webhooks.constructEvent(
    req.body,
    req.headers['stripe-signature'],
    WEBHOOK_SECRET, // proves the call really came from Stripe
  );

  if (event.type === 'payment_intent.succeeded') {
    const intent = event.data.object;
    await markOrderPaid(intent.metadata.orderId); // trusted truth
  }

  res.json({ received: true });
});

So the client's job and the server's job split cleanly. The client starts the payment and shows a hopeful "we're processing your order." The server, via the webhook, confirms it and flips the order to paid. Those are two different facts arriving through two different channels, and conflating them — treating the client's optimistic result as the settled truth — is the bug that gets apps double-charging, under-charging, or handing out product for free.

The client can tell you a payment started. Only the server, via the provider's webhook, can tell you it succeeded. Never let the browser be the thing that says "paid."

This maps exactly onto the server-state idea from the auth article: the important truth lives on the server, and the client holds a hopeful, possibly-stale view of it. Payments are the highest-stakes version of that same pattern, which is why the discipline matters more here than anywhere.

So How Hard Is It, Really?

Honestly? Less than the fear suggests, if you respect the two lines. Stripe has done the genuinely hard parts — the card handling, the PCI scope, the fraud tooling. What's left for you is smaller than people expect, but it's unforgiving about correctness.

Your real work is three things. Render Stripe's Element so the card never touches you — mechanical, and Stripe hands you the components. Kick off the payment from the client and, critically, treat the client-side result as "started," not "done." And build the webhook handler on your backend as the sole authority that marks an order paid, verifying the signature so nobody can forge that call. That's the shape of it. It's not a huge amount of code. It's a small amount of code where being casually wrong costs actual money, which is a very different kind of hard than "lots of code."

How I'd Approach It

Strip it to decisions:

The card number is radioactive. Use Stripe Elements so it never touches your JS or server. Don't negotiate with PCI scope — avoid it.
The client starts the payment; it does not confirm it. Show "processing," never "paid," from a client callback.
The webhook is the source of truth. An order becomes paid on your server, when Stripe tells your server it succeeded — and never before.
Verify the webhook signature. Otherwise anyone can call your endpoint and claim they paid.
Buy, don't build. This is the domain where rolling your own is not clever, it's negligent.

The reason payments feel scarier than they are is that they punish the exact habit web development otherwise rewards: trusting the client. Everywhere else, an optimistic UI that assumes success is good UX. Here, an optimistic UI that records success is a liability. Once you internalize that the browser can only ever say "I tried" and the server is the only thing that can say "it worked," the whole domain stops being frightening and becomes just careful — two clean lines, respected every time.

The next article stays with the values that are deceptively easy to get wrong and quietly ruin things: time and dates in React — timezones, storage, and the bugs that only surface at the worst possible hour.

If you've got a checkout that marks orders paid from a client callback, that's the second line crossed, and it's worth fixing before it costs you. Tell me how your success path works and I'll tell you where the hole is.

Internationalization Isn't Translation: What Actually Breaks

Maksym Kuzmitskyi (MaximusFT) — Tue, 12 May 2026 00:00:00 +0000

Ask most developers what internationalization means and you'll get the same answer: instead of writing "Save" in your JSX, you look up a key in a dictionary and get "Save" or "Enregistrer" depending on the user's language. And they're right — that is part of it. It's also the easy 10%, and it's the part that makes people underestimate the whole thing.

Because a translated string is not a translated interface. The moment you actually ship to another language, the interesting failures show up, and none of them are about the words. A date renders as 7/18/2026 to an American and 18/07/2026 to nearly everyone else. A price needs a different currency symbol, in a different position, with a comma where you had a period. "1 item" versus "5 items" is trivial in English and a genuine grammar problem in languages with six plural forms. And in Arabic or Hebrew the entire layout flips direction. None of that is a dictionary lookup.

So this article is about the 90% — what internationalizing a React app actually involves once you stop thinking of it as translation and start thinking of it as formatting and loading, which is what it really is.

The Reframe: It's Formatting, Not Words

Here's the shift that made i18n click for me. Stop picturing a dictionary. Picture a formatting engine.

The hardest parts of internationalization aren't the strings you wrote — they're the values you render. A date is a value that has to be formatted for a locale. A number is a value. A currency amount is a value. A count that decides between "item" and "items" is a value running through a locale's plural rules. The English strings are static and easy; the dynamic values are where every locale disagrees, and where a naive app quietly produces wrong output that looks fine to you and broken to them.

Translation handles the words you wrote. Internationalization handles the values you render. The second one is the hard part, and it's the part people skip.

The good news is you don't implement any of this yourself. The browser ships a full formatting engine — the Intl API — and the React libraries are wrappers that make it ergonomic.

Formatting Values the Right Way

The instinct, when you need a date or a price in the UI, is to build the string by hand — grab the month, slap it together, append a currency symbol. That instinct is exactly the bug, because the format itself is locale-dependent, not just the numbers inside it.

The Intl API already knows every locale's rules. You give it a value and a locale; it gives you correct output:

// Dates: same instant, formatted for the user's locale.
new Intl.DateTimeFormat('en-US').format(date); // "7/18/2026"
new Intl.DateTimeFormat('de-DE').format(date); // "18.7.2026"

// Currency: symbol, position, and separators all differ by locale.
new Intl.NumberFormat('en-US', { style: 'currency', currency: 'USD' })
  .format(1234.5); // "$1,234.50"
new Intl.NumberFormat('de-DE', { style: 'currency', currency: 'EUR' })
  .format(1234.5); // "1.234,50 €"

Look at what you're not deciding: where the currency symbol goes, whether the thousands separator is a comma or a period, the order of day and month. You hand over the value and the locale and get correct output. Building any of that by hand isn't just more code — it's code that's confidently wrong in locales you don't personally read.

Then there's pluralization, which English makes look trivial and other languages do not. "1 item" / "2 items" is a two-case rule; Polish and Arabic have far more, and a hardcoded count === 1 ? 'item' : 'items' is simply broken there. This is why the string libraries use the ICU message format, which encodes plural rules per locale:

{count, plural, one {# item} other {# items}}

You write the rule once; the library picks the right form for whatever locale is active, using the same Intl plural data. You are never in the business of knowing Polish grammar — you're in the business of not hardcoding English grammar.

The React Side: Loading, Not Bundling

Now the part that's specifically a React and architecture problem, and the one that separates a demo from a real app: you cannot ship every language in your bundle.

Here's the trap. You wire up react-i18next or FormatJS, it works, and to make it work you import all your translation files at the top. Now every user downloads English, French, German, Japanese, and Arabic just to see the one language they actually use. Your bundle balloons with text 90% of users will never read, and it gets worse with every locale you add. A feature meant to serve more users made the app slower for all of them.

The right shape is to treat translation data as something you load on demand, the same way you'd code-split a route. The active locale's messages load when needed; the rest stay on the server until someone actually switches:

// Load only the active locale's messages, not all of them.
async function loadMessages(locale: string) {
  const messages = await import(`../locales/${locale}.json`);
  return messages.default;
}

That dynamic import is the whole difference. A user on French downloads French. Switch to German and German loads then — a small, one-time fetch — instead of everyone paying for every language up front. The i18n libraries support this directly; the mistake is not the library, it's statically importing everything because the demo did.

This is the same instinct the whole series keeps returning to: the naive version loads everything eagerly, and the production version loads what's needed when it's needed. Translations are just data, and data that most users won't touch belongs behind a lazy load.

One More Thing: Direction

A short but real one, because it's the part that turns a "translated" app back into an untranslated-looking one. Some languages — Arabic, Hebrew, Persian — read right-to-left, and that's not a font setting, it's a layout inversion. Your sidebar moves to the other side, your icons mirror, your text aligns the other way.

The workable answer is to stop thinking in "left" and "right" and start thinking in "start" and "end." Modern CSS logical properties — margin-inline-start instead of margin-left, padding-inline-end instead of padding-right — flip automatically with the document direction. Set dir="rtl" on the root for RTL locales and a layout built on logical properties reorients itself. Build it on hardcoded left/right and you get to audit every component by hand. It's cheap if you do it from the start and expensive if you retrofit — which is a good reason to reach for logical properties by default even in a single-language app.

How I'd Approach It

Strip it to decisions:

It's formatting, not translation. The strings are easy; the values — dates, numbers, currency, plurals — are where locales actually disagree.
Never format values by hand. Use Intl (via your i18n library). It already knows every locale's rules; you never do.
Use ICU message format for plurals. Don't hardcode English's two-case grammar into a multi-locale app.
Load locales on demand, don't bundle them all. Dynamic-import the active language; leave the rest on the server.
Build layout on logical properties. start/end, not left/right, so RTL is a setting and not a rewrite.

I used to think of i18n as a chore you tack on at the end — extract the strings, hand them to translators, done. That framing is why so many "internationalized" apps still show a German user an American date and an Arabic user a left-to-right layout. The strings were never the hard part. The hard part is that every locale formats values differently and reads in its own direction, and the app has to be built to bend to that instead of assuming the world works like the machine you developed on. Get the formatting and loading right and translation is the small, boring finish — which is exactly where it should sit.

Speaking of values that quietly differ everywhere and ruin your day when you get them wrong — the next article is about handling money in React: what taking a payment actually requires, and why the client should never be the thing that decides you got paid.

If you've got an app that "supports" multiple languages but still leaks the developer's locale — an English date here, a broken plural there — that's the formatting-not-translation gap. Tell me what's showing wrong and I'll point you at which piece is missing.

DEV Community: Maksym Kuzmitskyi (MaximusFT)

Barrel Files: The Import You Love and the Bundle You Hate

What a barrel actually is

The cost hides where you're not looking

The worst offender: the app-wide barrel

When a barrel earns its place

What I actually do

The real lesson isn't about barrels

The shared/ Folder Is Not a Place, It's a Promise

Why the drawer fills up

The test that actually works

Make the boundary a wall, not a suggestion

Digging out of one you already have

A word on the barrel

The folder was never the problem

React in 3D: When Becomes

The Scene Graph Is Just Another Tree

VR and AR Are Just More of the Same Realization

The Thing This Whole Series Was Actually About

How I'd Approach It — and Where the Series Lands

React Native: What 'Learn Once, Write Anywhere' Really Means

There Is No DOM. That's the Whole Shift.

Styling: It Looks Like CSS and Isn't

Just Use Expo

The Instinct That Actually Needs Retraining

How I'd Approach It

React on the Desktop: When a Window Beats a Tab

What a Browser Tab Genuinely Can't Do

The Two Tools, and the Real Tradeoff

The Part That's Actually Different: Two Processes and a Bridge

How I'd Approach It

Documenting Components: The Only Docs That Don't Rot

Why the Wiki Always Loses

The Props Table Should Come From the Props

Living Examples Beat Screenshots

How I'd Approach It

Design Prototyping for React: Where the Architecture Actually Starts

A Design Has Structure, Not Just Appearance

Same Component, Different States — the Thing Static Mockups Hide

This Is a Conversation, Not a Handoff

How I'd Approach It

Sending Email from a React App: A Backend Problem in Disguise

The Line: The Client Never Sends Email

Why You Don't Talk to SMTP Yourself

The Genuinely Weird Part: Email Rendering Is Stuck in 2005

How I'd Approach It

File Upload in React: The Input Is Easy, the File Is Not

The First Decision: Your Server Shouldn't Touch the File

The Second Reality: The Upload Is a Process, Not a Request

The Third Reality: Big Files Need to Survive a Dropped Connection

Don't Forget: The File Is Untrusted

How I'd Approach It

Time in React: The Bugs That Only Show Up at 2 AM

The One Rule That Prevents Most of It

Why new Date() Keeps Betraying You

Reach for a Real Library — and Watch Temporal

The Traps That Remain

How I'd Approach It

Payments in React: The Client Never Decides You Got Paid

The First Line: Never Touch the Card Number

The Second Line: The Client Doesn't Decide

So How Hard Is It, Really?

How I'd Approach It

Internationalization Isn't Translation: What Actually Breaks

The Reframe: It's Formatting, Not Words

Formatting Values the Right Way

The React Side: Loading, Not Bundling

One More Thing: Direction

How I'd Approach It

React in 3D: When
Becomes

Why `new Date()` Keeps Betraying You