@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

1import { watchEffect } from 'vue'
2
3// bind ref as a variable
4let count = $ref(0)
5
6watchEffect(() => {
7  // no need for .value
8  console.log(count)
9})
10
11// assignments are reactive
12count++
13
14// get the actual ref
15console.log($$(count)) // { value: 1 }

Macros can be optionally imported to make it more explicit:

1// not necessary, but also works
2import { $, $ref } from 'vue/macros'
3
4let count = $ref(0)
5const { x, y } = $(useMouse())

Global Types

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

1/// <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.

1import { shouldTransform } from '@vue/reactivity-transform'
2
3shouldTransform(`let a = ref(0)`) // false
4shouldTransform(`let a = $ref(0)`) // true

transform

1import { transform } from '@vue/reactivity-transform'
2
3const src = `let a = $ref(0); a++`
4const {
5  code, // import { ref as _ref } from 'vue'; let a = (ref(0)); a.value++"
6  map
7} = transform(src, {
8  filename: 'foo.ts',
9  sourceMap: true,
10
11  // @babel/parser plugins to enable.
12  // 'typescript' and 'jsx' will be auto-inferred from filename if provided,
13  // so in most cases explicit parserPlugins are not necessary
14  parserPlugins: [
15    /* ... */
16  ]
17})

Options

1interface RefTransformOptions {
2  filename?: string
3  sourceMap?: boolean // default: false
4  parserPlugins?: ParserPlugin[]
5  importHelpersFrom?: string // default: "vue"
6}

transformAST

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

1import { transformAST } from '@vue/reactivity-transform'
2import { parse } from '@babel/parser'
3import MagicString from 'magic-string'
4
5const src = `let a = $ref(0); a++`
6const ast = parse(src, { sourceType: 'module' })
7const s = new MagicString(src)
8
9const {
10  rootRefs, // ['a']
11  importedHelpers // ['ref']
12} = transformAST(ast, s)
13
14console.log(s.toString()) // let a = _ref(0); a.value++