Most React courses teach in the same order. Syntax first. Then hooks. Then a small app. Then, somewhere near the end — if there's time — how a real project is actually organized.
I understand why. You can't explain a provider tree to someone who doesn't know what a component is. The order makes sense on paper.
But there's a gap in the middle that nobody really covers, and I think it's the reason so many people finish a course and still feel like they can't read real code.
Reading code and understanding code are different things
You can stare at this for an hour:
<AnalyticsWidgetSummary
title="Weekly sales"
total={714000}
color="warning"
chart={{ series: [22, 8, 35, 50, 82, 84, 77, 12] }}
/>
And you'll "understand" it. Title is a string. Total is a number. Color is a string that's probably one of a few allowed values. Chart is an object with a series array.
Now: what does color="warning" actually change? Where does "warning" come from? Is it defined in this file? No. In the component? No. It's in a theme object, three directories away, that gets injected through a provider wrapped around the entire app in a file the student has never opened.
None of that is visible from reading the line. You only learn it by changing the value and watching what happens — or better, by changing the theme and watching six unrelated components shift at once. That's the moment the concept lands. Not before.
Sandboxes solve the setup problem, not the structure problem
The usual answer here is CodeSandbox or StackBlitz, and they're genuinely good tools. Setup friction goes to zero, the student clicks a link and there's running code. Great.
But look at what's actually in most educational sandboxes:
- One file, maybe three
- No routing
- No theme provider
- No barrel exports
- No
features/folder, nolayouts/, no shared component library - State that lives exactly where you'd expect it to live
That's a curated environment. It's useful for isolating one concept — and that's what it's for — but it's the opposite of what the student will face at their first job. Real apps are five providers deep before anything renders. Components import from @/components which re-exports from somewhere else which re-exports from somewhere else. Half the props come from a context you can't see in the file you're looking at.
So we teach on tidy code and then hand people messy code and act surprised when the transition is rough.
The missing link: code and canvas, pointing at each other
There's one more thing sandboxes structurally can't do, and I think it matters more for learning than anything else on this list.
In a sandbox, the editor and the preview are two separate worlds. You have code on the left, a rendered iframe on the right, and nothing connects them. If a student sees a card on screen and wants to know which JSX made it, they have to guess: search for the text, scroll, open three files, guess again. If they change a line of code, they see something change on the right, but they have to work out for themselves which change was theirs.
That guessing step is where beginners lose the thread. It's a translation tax paid on every single interaction.
Now flip it. Selection is shared in both directions:
- Click a JSX node in the code, the matching element lights up on the canvas. "This is what that line draws." No searching.
- Click an element or prop on the canvas, the exact JSX node or prop gets selected and highlighted in the code. “That’s the line that made this — and the property that controls it.” No guessing..
And editing works both ways too:
- Type in the code, the canvas updates live.
- Change a prop on the canvas, and the corresponding code updates — the changed prop briefly highlights.
Sounds small. It isn't. What it does is collapse the gap between symbol and thing. Beginners spend enormous energy holding an unstable mental map between "this text" and "that rectangle on screen." When the tool holds the map for them, that energy goes back into the actual concept.
It's the same reason browser devtools were such a leap for learning CSS. Before devtools you edited a stylesheet and reloaded and squinted. After devtools, you clicked the element and saw which rules applied. Nobody argues devtools made people worse at CSS. It just removed the guessing.
React never really got that moment. The component tree is a runtime construct, the JSX is source text, and the two have historically lived in separate windows with no line between them. Two-way selection is that line.
And this genuinely is not something CodeSandbox or StackBlitz can bolt on. They run your code in an iframe — they can host it and hot-reload it, but they don't have a live mapping from the rendered DOM node back to the exact AST node that produced it, especially once that node came out of a .map(), or a ternary, or a component defined in a different file. That mapping is the hard part, and it's the part that turns "here's your code running" into "here's your code, and here's what each piece of it is."
For a student, the practical effect is that the feedback loop drops from minutes to zero. Click, see, change, see. Repeat forty times in a session. That's not a nicer UI — that's a different learning rate.
The dependency graph is the thing you're actually teaching
Here's the part I think gets underrated. When a student says "I can't find where this comes from," they're not asking a syntax question. They're asking a graph question.
Every React codebase is a dependency graph. Files import files, barrels re-export barrels, a component pulls a hook that pulls a context that's provided six levels up. The rendered UI is just one projection of that graph. Most of the confusion beginners have — "where does this prop come from," "why did changing that file break this screen," "which of these five index.ts files is the real one" — is them trying to traverse a graph they can't see.
Courses teach the tree (component hierarchy). They mostly skip the graph (module dependencies). But the graph is what you navigate every day at work.
So the exercise gets better if you make the graph visible:
-
Trace one import chain end to end.
AnalyticsWidgetSummary→@/components/chart→chart/index.ts→chart-widget.tsx. Three re-exports to get to real code. That's not unusual; that's Tuesday. - Ask "what breaks if I delete this file?" and then actually look at the answer. Inbound edges are a concept you can feel, not just define.
- Show a broken edge. Rename an export and watch which parts of the graph go red. Beginners learn far more from a targeted break than from a working example.
There's a practical angle too: real templates often have edges that don't resolve — a missing peer dep, an optional import, a path alias nobody configured. Traditionally that's a hard stop; nothing renders, the student is dead in the water in minute three. It doesn't have to be. If the tool can bypass an unresolved import and keep rendering the rest of the graph, a broken edge becomes a lesson instead of a blocker. (We wrote about the mechanics of that separately, in Don't just find the broken import. Bypass it.)
A student who can read a dependency graph can onboard onto any codebase. A student who only knows hooks can onboard onto the one they were taught.
The thing that's usually a diagram
Every React curriculum I've seen has a moment where the instructor draws a box, puts smaller boxes inside it, and says "so the provider wraps everything, and the components underneath can read from it."
The diagram is correct. It's also inert. It doesn't respond when you poke it. Nobody has ever learned what a provider does by looking at a rectangle.
What if instead of the diagram, the student opened the actual app — a real, shipped, slightly messy admin template — clicked into a card buried four levels deep inside a .map() inside a conditional inside a layout component, and changed one prop? And saw both the rendered result and the exact source diff at the same time?
That's not a replacement for the explanation. It's the thing the explanation is about, made touchable.
What this actually looks like in practice
Concretely, here's the exercise I keep imagining for week one, before the student has written a single line of React themselves:
1. Open a real template. Not a teaching example — something that actually shipped. Material Kit React, shadcn-admin, whatever. Entry file, straight from disk. No npm install, no dev server, no "wait for it to build."
2. Find one thing on screen. "See that revenue card in the top left? Click it." The corresponding JSX highlights in the code — they didn't search for it, they pointed at it. Then walk back up: main.tsx → DashboardPage → OverviewAnalyticsView → AnalyticsWidgetSummary. Four hops. The student just learned what a component tree is, by walking one.
2.5. Go the other direction. Put the cursor on a random JSX node in the code and watch the canvas highlight what it draws. Do it on a node inside a .map() so they see one line of code producing eight things on screen. That single observation explains lists better than any lecture on key props.
3. Change one prop — from both sides. Edit total={714000} → total={928000} in the code, watch the number change. Then change the next card's value on the canvas instead, and watch the one-line diff appear in the source. Same operation, two directions. That's props, and that's also the first time most students really believe the UI is the code.
3.5. Follow one import out of the file. Where does AnalyticsWidgetSummary actually live? Not the import line — the real file, past the barrels. Two or three hops through the dependency graph. Do it once by hand so they know what the tool is doing for them later.
4. Change something in the theme. Watch six other components move. That's context. No diagram required.
5. Break something on purpose. Pass a string where a number goes. See what React does. Fix it.
None of that requires the student to know how to write React yet. It requires them to know how to read it and poke it — which is honestly what most junior work is anyway. You're rarely writing a new app from scratch. You're finding the thing in someone else's codebase and changing it without breaking three other things.
The objection I keep coming back to
The obvious pushback: isn't this just teaching people to be dependent on a visual tool? If they can't find the file by hand, have they actually learned anything?
I think that's a fair worry, and it depends entirely on how it's used. If the tool does the navigation for them and they never look at the path, no, they haven't learned much. If the tool shows them the path — literally, the breadcrumb of components it walked through, and the file each one lives in — then it's closer to training wheels than a crutch. They see the structure repeatedly, in a real codebase, until it stops being mysterious.
The other objection: real templates are messy, and messy is confusing for beginners. Also fair. But they're going to hit messy eventually, and I'd rather they hit it with an instructor in the room than alone on day three of a new job.
Why I'm thinking about this at all
I build a tool that does the "open a real React app with no build step and edit it" part — CrossUI Studio. It wasn't built for education. It was built because I got tired of running npm install on a template just to see whether the card component was worth using.
But the education angle keeps coming up. People teaching React tell me the hardest part isn't syntax — it's the gap between "I can write a component" and "I can find my way around a codebase someone else wrote." That gap is not a knowledge problem. You can't lecture it away. It's a familiarity problem, and familiarity comes from time spent poking at real things.
So the question I actually want to ask: has anyone teaching React tried starting with a real app instead of a curated one? Bootcamps, university courses, even internal onboarding for new hires. Did it work? Did students find it empowering, or just overwhelming? Is there a reason this is a bad idea that I'm not seeing from where I sit?
Genuinely curious. I'm on the tool side of this, not the teaching side, and I'd rather hear from people who've actually stood in front of a room of beginners.
If you want to try the mechanic yourself: Guest mode opens instantly, no account. Point it at a template, click something, and see how far down it goes.
Top comments (0)