@vue/reactivity-transform

@vue/reactivity-transform

⚠️ This is experimental and the proposal has been dropped. The feature is now marked as deprecated and will be removed from Vue core in 3.4.

See reason for deprecation here.

Basic Rules

• Ref-creating APIs have $-prefixed versions that create reactive variables instead. They also do not need to be explicitly imported. These include:
  • ref
  • computed
  • shallowRef
  • customRef
  • toRef
• $() can be used to destructure an object into reactive variables, or turn existing refs into reactive variables
• $$() to "escape" the transform, which allows access to underlying refs

import { watchEffect } from 'vue'

// bind ref as a variable
let count = $ref(0)

watchEffect(() => {
  // no need for .value
  console.log(count)
})

// assignments are reactive
count++

// get the actual ref
console.log($$(count)) // { value: 1 }

Macros can be optionally imported to make it more explicit:

// not necessary, but also works
import { $, $ref } from 'vue/macros'

let count = $ref(0)
const { x, y } = $(useMouse())

Global Types

To enable types for the macros globally, include the following in a .d.ts file:

/// <reference types="vue/macros-global" />

API

This package is the lower-level transform that can be used standalone. Higher-level tooling (e.g. @vitejs/plugin-vue and vue-loader) will provide integration via options.

shouldTransform

Can be used to do a cheap check to determine whether full transform should be performed.

import { shouldTransform } from '@vue/reactivity-transform'

shouldTransform(`let a = ref(0)`) // false
shouldTransform(`let a = $ref(0)`) // true

transform

import { transform } from '@vue/reactivity-transform'

const src = `let a = $ref(0); a++`
const {
  code, // import { ref as _ref } from 'vue'; let a = (ref(0)); a.value++"
  map
} = transform(src, {
  filename: 'foo.ts',
  sourceMap: true,

  // @babel/parser plugins to enable.
  // 'typescript' and 'jsx' will be auto-inferred from filename if provided,
  // so in most cases explicit parserPlugins are not necessary
  parserPlugins: [
    /* ... */
  ]
})

Options

interface RefTransformOptions {
  filename?: string
  sourceMap?: boolean // default: false
  parserPlugins?: ParserPlugin[]
  importHelpersFrom?: string // default: "vue"
}

transformAST

Transform with an existing Babel AST + MagicString instance. This is used internally by @vue/compiler-sfc to avoid double parse/transform cost.

import { transformAST } from '@vue/reactivity-transform'
import { parse } from '@babel/parser'
import MagicString from 'magic-string'

const src = `let a = $ref(0); a++`
const ast = parse(src, { sourceType: 'module' })
const s = new MagicString(src)

const {
  rootRefs, // ['a']
  importedHelpers // ['ref']
} = transformAST(ast, s)

console.log(s.toString()) // let a = _ref(0); a.value++

Similar packages

Other packages similar to @vue/reactivity-transform

mobx

MobX is a state management library that also focuses on making state as reactive as possible. It differs from @vue/reactivity-transform in that it's not tied to the Vue ecosystem and offers its own set of APIs for creating observables, computed values, and reactions. MobX can be used with any framework, making it more versatile, but potentially more verbose for Vue-specific projects.

immer

Immer is a package that allows you to work with immutable state in a more convenient way. While it doesn't offer reactive programming features out of the box like @vue/reactivity-transform, it simplifies the process of updating complex state objects in an immutable manner. Immer is framework-agnostic and focuses on producing the next immutable state by applying a draft state, which is a different approach compared to the reactive transformations provided by @vue/reactivity-transform.