CHAPTER 00 · ORIENTATION
A Paradigm Shift: From Writing Code to Defining and Verifying Systems
You already know how to program. This guide doesn't teach programming. It helps you carry your engineering instincts into the TypeScript full-stack ecosystem, and learn to let coding agents write most of the code while you keep firm control of direction and quality.
- Name the three default assumptions that change when you move to TS full-stack — not just "the syntax is different".
- Use three depth levels — Deep / Use / Aware — to decide how far to learn any new term.
- Understand LinkNote, the practice project that runs through the whole guide, and pick a learning path.
A confusion you will probably hit
An engineer with years of backend experience opens a Next.js project generated by an agent. They recognize almost every line: const, async, functions, objects… Yet they still can't say: does the code in this file run on the server or in the user's browser? Why didn't the page update when a variable changed? Why does the agent insist "this needs 'use client'"?
Where the answer lies: it isn't the syntax. Three default assumptions have been quietly swapped out. Swap them back in your head and most of the confusion disappears at once:
- "Where does this code run?" no longer has a fixed answer. In Java or Go, your code runs on "the server" and the browser just displays the result. In TS full-stack, code in the same language, the same project, even the same folder may run at build time, on the server, in the browser after being bundled and shipped, or across hundreds of edge locations worldwide. You must always know where a piece of code runs, because that decides what it can reach (the database? the user's mouse click?) and what it must never leak (secrets).
- The UI is no longer changed imperatively; it is computed declaratively. You are used to "event arrives → find that element → modify it". React's model is UI = f(state). You only change state; the framework recomputes the UI and figures out the differences. Change a plain variable instead of "state" and of course nothing moves.
- Who writes the code has changed. Agents can now produce most implementation code. Your core output becomes clear intent, precise constraints, verifiable acceptance criteria, and review of what the agent produces. That demands precise enough vocabulary to describe what you want, and deep enough understanding to spot mistakes.
The next fifteen chapters essentially take these three assumptions apart one by one and replace them with new mental models.
An analogy: what happened when we moved from assembly / C to OOP?
You may have lived through that shift, or at least heard about it. It shares one very useful property with today's shift — and differs in one crucial way.
What's the same: abstraction moves up, but lower-level knowledge never expires. C programmers stopped allocating registers by hand, yet the ones who understood stack frames and memory layout debugged segfaults ten times faster. Java programmers stopped freeing memory, yet the ones who didn't understand references and GC still wrote memory leaks. Likewise, today an agent can write you a complete React component — but if you don't understand the rule "state change → re-render", you won't see why it hammers the API in an infinite loop.
What's different: compilers are deterministic; agents are not. The same C code compiles the same way every time, and compilers almost never get it wrong, so you can trust them almost completely. Agents are probabilistic: the same request may produce two different implementations; they can be confidently wrong; they can quietly change things you didn't ask them to touch. So this shift adds a core skill the old one didn't need as much: verification. You need to make agent output checkable (types, tests, screenshots, logs) and have the judgment to check it.
"An agent is just a higher-level compiler" only holds for the "abstraction moves up" part. On reliability, it is more like a very capable, extremely fast colleague on their first day, who knows nothing about your project: you need to give them clear requirements, project conventions and acceptance criteria, and review their work. This colleague never gets tired or impatient — but also never volunteers "actually, I didn't understand the requirement".
Three depth levels: what to understand deeply, what to just use
The TS ecosystem has an enormous number of names. Mastering all of them is neither realistic nor necessary. Every topic in this guide carries a depth tag so you can budget your effort:
Deep
Understand the internal mechanism. This is what lets you notice, locate and explain why when an agent gets it wrong. Few items, but for each one you should be able to draw it and predict outcomes.
Use
Use fluently, read comfortably, name precisely. This is your vocabulary for talking to agents. You don't need the source code, but you need to know what problem it solves, the common usage and the traps.
Aware
Know it exists, what it solves and when to consider it. This is your field of view for technology choices and system design. Dig in with an agent when you actually need it.
The table below is the guide's "effort budget". You don't need to understand it all on first read — each term is explained where it first appears.
| Topic | Depth | Why this depth | Ch. |
|---|---|---|---|
| Event loop, Promises, async/await | Deep | Root of every "wrong order", "hangs", "race" bug; an interview staple | 03 |
| TS type system: structural typing, narrowing, generics, type erasure | Deep | To read agent-written types, and to know "types don't exist at runtime" so boundaries must be validated | 04 |
| HTTP, cookies, CORS, caching | Deep | Auth, cross-origin and cache invalidation are where agents "fix one thing, break another" | 05 |
| React rendering model: state → re-render, effects | Deep | Overusing useEffect is one of the most common agent mistakes | 06 |
| Server/client boundary: SSR, RSC, hydration | Deep | Decides where code runs, how data flows, whether secrets leak | 07 |
| LLM calls: tokens, context, streaming, tool calling | Deep | Determines the cost, latency and reliability of every AI feature | 11 |
| Agent loop and context management | Deep | Both what you'll build and the tool you'll use every day | 12, 13 |
| Next.js / TanStack Start routing and data loading | Use | The bulk of daily work; API details can be looked up | 07 |
| Zod, Drizzle / Prisma, TanStack Query, Hono | Use | High-frequency libraries you must read and name | 08 |
| Tailwind CSS, shadcn/ui | Use | The default combo agents use for UI; you need to read and tweak it | 05 |
| Vitest, Playwright, type checking, CI | Use | Your main weapons for verifying agent output | 10 |
| Vercel / Cloudflare / self-hosted deployment | Use | Master one path; know how the other two differ | 09 |
| Bundler internals (Vite, Rolldown, Turbopack) | Aware | Know what they are; you'll rarely tune them | 01 |
| Monorepo tools, state libraries, animation libraries | Aware | Bring in when a concrete need appears | 10 |
When unsure how deep to go on a new term, ask: "If the agent got this wrong, how much would I need to understand to notice?" If the failure would be silent and serious (corrupted data, a security hole, a performance collapse), lean toward Deep. If it would surface immediately as an error, Use is enough.
The running project: LinkNote
To avoid a pile of unrelated examples, the whole guide revolves around one small application. Every time you learn a concept, you'll see exactly where it lands in this app.
- The user pastes a URL → the server fetches the page → an LLM produces a summary and tags (streamed to the UI).
- The list page supports tag filtering and search; each bookmark has a status: pending / done / failed.
- "Ask my bookmarks": an agent that can call a "search bookmarks" tool to answer "What did the React articles I saved last month say?"
- Deployed to Vercel, to Cloudflare, and to your own server.
You don't need to understand every box yet. When you finish Chapter 08, come back to this diagram: for every arrow you should be able to say what data it carries, over which protocol, and where it's validated.
Map and two paths
01 Ecosystem map
Runtimes, package managers, bundlers, frameworks, platforms — and how they relate.
02 Setup
Node, pnpm, editor, tsconfig, and your first running project.
03 JS runtime
Event loop, async, closures, modules — the most important "Deep" chapter.
04 TS type system
Structural typing, narrowing, generics, runtime validation at boundaries.
05 Web platform
HTTP, the browser, HTML/CSS, Tailwind.
06 React
UI = f(state), components, hooks, when not to use effects.
07 Rendering & meta-frameworks
CSR/SSR/RSC, Next.js and TanStack Start.
08 Backend & data
APIs, validation, ORMs, auth, end-to-end types.
09 Deployment
Vercel vs Cloudflare vs self-hosting.
10 Engineering
Tests, lint, CI, monorepos, observability.
11 AI apps
LLM APIs, streaming, structured output, tool calling, RAG.
12 Agents & harnesses
The agent loop, MCP, skills, context engineering.
13 Driving coding agents
Spec → plan → implement → verify, and how to say what you mean.
14 System design & interviews
A full-stack design framework and common interview questions.
15 Glossary & plan
Terms, an 8-week plan, a self-assessment checklist.
Path A: ship something fast (~2 weeks)
00 → 01 → 02 → 03 → 04 → 06 → 07 → 08 → 11 → 13. The bold ones are the Deep chapters you must not skip. Come back to the rest when a problem sends you there.
Path B: a full transition (~8 weeks)
Read every chapter in order, do each chapter's "Tell the agent" exercise, and actually build it in LinkNote. Chapter 15 has a week-by-week plan.
How to read this guide
Every chapter follows roughly the same structure, which doubles as a learning loop:
- Start with the opening question. It's a concrete phenomenon your current knowledge can't explain. Guess an answer first (no need to write it down).
- Follow the mechanism. Pay special attention to the interactive diagrams: click "Next" and watch the intermediate state at every step, not just the final result.
- Return to LinkNote. See what the concept looks like in a real project.
- Practice "Tell the agent". Every chapter contrasts a vague prompt with a precise one. Use the precise version with your own agent and compare the output.
- Do the self-check. The questions deliberately change a condition — they test transfer, not recall. If you can't answer, go back to the relevant section.
While learning, treat your agent as an on-call tutor — but ask questions that can be checked:
The second version provides your background, a concrete example, the intermediate process you want to see and a way to test yourself — the very same four things you'll give an agent later when handing it development work.
Engineers in transition easily start by "setting up the perfect learning environment": research monorepos first, configure ten lint rules first, build an automated agent workflow first… and three weeks later there isn't a single working page. This guide's advice: get the simplest version of LinkNote running and deployed first, then come back for the matching tool when a real problem shows up. Shipping beats preparing.
Self-check
1. A colleague says: "With agents, nobody needs to learn low-level stuff like the event loop." Using this chapter's analogy, what's right and what's wrong about that?
Right: as abstraction moves up, you indeed don't need to hand-write every line that manages async ordering, just as Java programmers don't free memory by hand.
Wrong: lower-level knowledge never expires when it comes to debugging and review — and an agent is not a deterministic compiler; it makes mistakes. Async-ordering bugs are often silent (data occasionally wrong), so by this chapter's rule of thumb that knowledge is Deep.
2. You meet the word "Turbopack" for the first time. Which depth level would you put it in, and why?
Aware. It's a bundler (a tool that turns source code into files a browser can load). When it breaks, it usually surfaces as an explicit build error rather than silently producing wrong business data, and you'll almost never configure it yourself. Knowing what it is — the same category as Vite — is enough.
3. Some code reads the database password and interpolates it into a page. Given the "first default assumption", what should you ask first?
"Where does this code run?" If it's bundled and shipped to the browser (a client component), the password leaks to every user. If it only runs on the server, the risk is whether the rendered output carries sensitive data. Chapter 07 explains how to recognize and enforce that boundary.