Vue Guide
Build a counter in Vue and the number on screen changes from count.value++ alone. Behind that convenience, machinery is running that tracks every read and write of the value. You can keep writing without knowing how it works and still ship something, but you will stall on "why does reassigning it stop being reactive?" and "why does destructuring break it?"
This guide aims to explain the Vue 3.5 API from its design intent. It is not a catalogue of syntax; it covers why each way of writing was chosen, and what breaks when you go against it.
About this guide
The subject is the Composition API and script setup. The Options API comes up when you need to read existing code, but it is not treated as something to write from scratch. Every code example is in TypeScript, and how far the types reach is part of the discussion.
The guide follows these principles throughout.
- Write with
script setupand TypeScript. The Options API is touched on only for reading existing code, never as something new to write - Make
ref()the first choice for declaring state. This is the policy the official documentation states as its recommendation, and chapter 2 cites the source - Extract reusable units into composables
- Use Pinia for state management
- Cover Nuxt 4 where server-side rendering is needed
- Leave out anything specific to Vue 2. Support ended at the end of 2023
Who this is for
- People who have manipulated the DOM in JavaScript and are looking for a way into a framework
- People writing Vue who have tripped over how reactivity behaves
- People with React experience who want to know how Vue's design thinking differs
Each chapter builds on the one before it, but the chapters from Vue Router onward can be read on their own.
Prerequisites
| Level | Knowledge | Notes |
|---|---|---|
| Required | Experience building screens with HTML and CSS | You do not need the syntax memorised |
| Required | Basic JavaScript syntax | Destructuring, arrow functions, and Promise notation are used without explanation. Where explaining Vue's behaviour demands it, though, the guide does go into how values are passed around |
| Recommended | Basic TypeScript type annotations | The examples are in TypeScript, but they do not use complicated types |
| Not needed | Vue 2 experience | Vue 2 reached end of support at the end of 2023 and is not covered here |
Tech stack
| Target | Version | Role |
|---|---|---|
| Vue | 3.5 | The framework itself. 3.6 is a candidate release, so it is not the baseline |
| TypeScript | 5 or later | Type annotations and checking via vue-tsc |
| Vite | 8 | Dev server and build |
| Vue Router | 5 | Navigation |
| Pinia | 4 | State management |
| Nuxt | 4 | Server-side rendering and file-based routing |
Chapter outline
The 20 chapters are split into six parts.
Part 1: Vue fundamentals
| Chapter | What it covers |
|---|---|
| 01 Setup and SFCs | Creating a project with create-vue, and the three-block structure of a single-file component |
| 02 Reactivity | Choosing between ref and reactive. Why reassignment and destructuring break |
| 03 Template syntax and directives | Attribute binding, conditionals, list rendering. Why key is needed |
| 04 Events and form input | Event modifiers and v-model. What changes when you add or drop the parentheses |
| 05 Computed properties and watchers | Caching in computed and side effects in watch. How to decide between them |
Part 2: The Composition API
| Chapter | What it covers |
|---|---|
| 06 script setup and the component contract | Declaring the boundary between parent and child as types with defineProps and defineEmits |
| 07 Lifecycle | The order hooks run in, and which work belongs where |
| 08 Composables | Extracting logic into functions. The shape of arguments and return values, and where cleanup is handed off |
| 09 Composables and server-side rendering | Ways of writing that break under SSR. The pitfalls of sharing state |
Part 3: Building components
| Chapter | What it covers |
|---|---|
| 10 v-model between components | Wiring two-way binding with defineModel |
| 11 Slots | Letting the parent render part of the component. Passing data with scoped slots |
| 12 provide / inject and custom directives | Passing values past the hierarchy, and the means to touch the DOM directly |
| 13 Teleport and Suspense | The mechanism for moving where things render, and the one for handling async waiting declaratively |
Part 4: Navigation and motion
| Chapter | What it covers |
|---|---|
| 14 Transitions | Enter and leave animations. The order classes are applied in, and the JavaScript hooks |
| 15 Vue Router basics | Route definitions, navigating from code, dynamic routes, nested routes |
| 16 Navigation guards and optimisation | Intercepting navigation, scroll control, lazy loading |
Part 5: State and data
| Chapter | What it covers |
|---|---|
| 17 Pinia | Defining and splitting stores. Why storeToRefs becomes necessary |
| 18 HTTP requests and data fetching | Where fetch logic lives, and how to handle environment variables |
Part 6: Nuxt and practice
| Chapter | What it covers |
|---|---|
| 19 Nuxt | File-based routing, useFetch, server APIs |
| 20 Practice: authentication and deployment | Building the login flow and deciding where the token lives. Placing the build output |
How each chapter is structured
Every chapter follows the same shape.
| Section | What goes in it |
|---|---|
| What you'll learn | What you will be able to do once you finish the chapter |
| Body | How the machinery works and how to make the call. Uses diagrams, tables, and code examples |
| Summary | The key points of the chapter |
| Related references | Existing guides to go deeper with, and links to the official documentation |
| What to read next | The next chapter, plus routes into related chapters in other parts |
How this fits with the other guides
This site already has guides organised by technology. This one narrows in on learning Vue as a framework, sending you to the JavaScript guide and the TypeScript guide for language features and to the Tailwind CSS guide for CSS. Which guide covers which stage across the whole site is laid out in the introduction.
The React guide sits alongside this one. Both are about composing components into a UI, but they hold state differently. React expresses a state update as a function call and puts the unit of re-rendering at the component. Vue embeds the tracking machinery in the value itself and updates only the places that depend on it. That difference surfaces in how key is handled and in whether memoisation is needed, so reading both widens the design options available to you.
How to read it
- New to Vue — read Part 1 in order, running the code as you go
- Writing Vue but unsure about the machinery — chapters 02, 05, and 08 are worth reading on their own
- Coming from React — get the difference in reactivity from chapter 02, then check how the parent-child contract is written in chapter 06
- Looking up a specific feature — open the relevant chapter directly from the outline above
With that, let's start with Setup and SFCs.