In Vue 3, why does the documentation recommend `const book: Book = reactive({...})` over passing a type argument as in `reactive<Book>({...})`?

## How `reactive()` is typed **`reactive()`** returns a deep reactive proxy of an object. With no extra help, TypeScript infers the proxy's type from the literal you pass: ```ts import { reactive } from 'vue' const book = reactive({ title: 'Vue 3 Guide' }) // { title: string } ``` That inferred type is often too narrow: a `year` field that the form fills in later does not exist on it, and adding `book.year = 2024` is a type error. So you need a way to say what the object will hold. ## The declared signature In Vue 3.5 the signature is `reactive<T extends object>(target: T): Reactive<T>`, where `Reactive<T>` is built on **`UnwrapNestedRefs<T>`**. The unwrapping mirrors runtime behaviour: a ref stored as a property of a reactive object is read and written **without `.value`**. ```ts import { reactive, ref } from 'vue' const state = reactive({ count: ref(0) }) state.count // number, not Ref<number> state.count++ // updates the inner ref ``` So the type you pass **in** and the type you get **out** are different types whenever the object contains refs. ## Why the type argument misleads With `reactive<T>()`, `T` constrains the **input**. Two consequences follow: 1. If `T` includes a `Ref` field, you write `T` with `Ref<number>` but read the result as `number`. The type you named is not the type you use, and the docs call this out as the reason not to use the generic argument. 2. If `T` has no refs, the argument and the output coincide, but you have still expressed the contract in terms of the input, and a later change that adds a ref field silently changes what readers see. ## What the documentation recommends Annotate the **variable** with an interface describing the shape you read and write: ```ts import { reactive } from 'vue' interface Book { title: string year?: number } const book: Book = reactive({ title: 'Vue 3 Guide' }) book.year = 2024 // ok: declared as optional ``` - The annotation is **checked**: TypeScript verifies that the unwrapped proxy type is assignable to `Book`. - Optional fields such as `year?` are **declared up front**, so later assignments type-check. - Readers see the public shape of the state in one interface, which can be exported and reused by functions that take the state. | Style | What the type describes | Docs advice | |---|---|---| | Inference only | The initial literal | Fine when the literal already has every field | | `const x: Book = reactive(...)` | The shape you read and write | Recommended for explicit typing | | `reactive<Book>(...)` | The input object | Not recommended | ## Arrays, collections and state shapes The annotation style extends naturally to larger state objects, which is where `reactive()` is most often used: ```ts import { reactive } from 'vue' interface Filters { query: string tags: string[] page: number sort?: 'price' | 'date' } const filters: Filters = reactive({ query: '', tags: [], page: 1 }) filters.sort = 'price' // ok filters.sort = 'name' // error: not in the union ``` 1. The empty `tags: []` literal would infer poorly on its own; the annotation gives it `string[]`. 2. A **literal union** such as `'price' | 'date'` is only available through a declared type; inference would widen `'price'` to `string`. 3. The same `Filters` interface can type a function parameter, `function toQuery(f: Filters)`, which then accepts the reactive object directly because its unwrapped type matches. ## The same idea for `computed()` `computed()` follows the inference-first rule too: `computed(() => book.title.length)` is a `ComputedRef<number>`. You can pass an explicit type, `computed<number>(() => ...)`, and a getter that returns something else becomes a type error at the definition. A getter-only computed's `value` is readonly in its type. ## Pitfalls - **Annotating with a type that has `Ref` fields**: the proxy exposes them unwrapped, so the annotation will not match what you read. - **Typing the literal instead of the variable**: `reactive({ title: 'x' } as Book)` asserts rather than checks, so a missing required field slips through; the annotation form checks it. - **Passing a primitive**: `reactive(0)` fails the `T extends object` constraint; primitives belong in `ref()`. - **Expecting annotation to change runtime behaviour**: it is types only; the proxy is identical either way.