babel-plugin-transform-vue-jsx

Babel plugin for Vue 2.0 JSX

Babel Compatibility Notes

• If using Babel 7, use 4.x
• If using Babel 6, use 3.x

Requirements

• Assumes you are using Babel with a module bundler e.g. Webpack, because the spread merge helper is imported as a module to avoid duplication.

• This is mutually exclusive with babel-plugin-transform-react-jsx.

Usage

1npm install\
2  babel-plugin-syntax-jsx\
3  babel-plugin-transform-vue-jsx\
4  babel-helper-vue-jsx-merge-props\
5  babel-preset-env\
6  --save-dev

In your .babelrc:

1{
2  "presets": ["env"],
3  "plugins": ["transform-vue-jsx"]
4}

The plugin transpiles the following JSX:

1<div id="foo">{this.text}</div>

To the following JavaScript:

1h('div', {
2  attrs: {
3    id: 'foo'
4  }
5}, [this.text])

Note the h function, which is a shorthand for a Vue instance's $createElement method, must be in the scope where the JSX is. Since this method is passed to component render functions as the first argument, in most cases you'd do this:

1Vue.component('jsx-example', {
2  render (h) { // <-- h must be in scope
3    return <div id="foo">bar</div>
4  }
5})

h auto-injection

Starting with version 3.4.0 we automatically inject const h = this.$createElement in any method and getter (not functions or arrow functions) declared in ES2015 syntax that has JSX so you can drop the (h) parameter.

1
2Vue.component('jsx-example', {
3  render () { // h will be injected
4    return <div id="foo">bar</div>
5  },
6  myMethod: function () { // h will not be injected
7    return <div id="foo">bar</div>
8  },
9  someOtherMethod: () => { // h will not be injected
10    return <div id="foo">bar</div>
11  }
12})
13
14@Component
15class App extends Vue {
16  get computed () { // h will be injected
17    return <div id="foo">bar</div>
18  }
19}

Difference from React JSX

First, Vue 2.0's vnode format is different from React's. The second argument to the createElement call is a "data object" that accepts nested objects. Each nested object will be then processed by corresponding modules:

1render (h) {
2  return h('div', {
3    // Component props
4    props: {
5      msg: 'hi',
6      onCustomEvent: this.customEventHandler
7    },
8    // normal HTML attributes
9    attrs: {
10      id: 'foo'
11    },
12    // DOM props
13    domProps: {
14      innerHTML: 'bar'
15    },
16    // Event handlers are nested under "on", though
17    // modifiers such as in v-on:keyup.enter are not
18    // supported. You'll have to manually check the
19    // keyCode in the handler instead.
20    on: {
21      click: this.clickHandler
22    },
23    // For components only. Allows you to listen to
24    // native events, rather than events emitted from
25    // the component using vm.$emit.
26    nativeOn: {
27      click: this.nativeClickHandler
28    },
29    // class is a special module, same API as `v-bind:class`
30    class: {
31      foo: true,
32      bar: false
33    },
34    // style is also same as `v-bind:style`
35    style: {
36      color: 'red',
37      fontSize: '14px'
38    },
39    // other special top-level properties
40    key: 'key',
41    ref: 'ref',
42    // assign the `ref` is used on elements/components with v-for
43    refInFor: true,
44    slot: 'slot'
45  })
46}

The equivalent of the above in Vue 2.0 JSX is:

1render (h) {
2  return (
3    <div
4      // normal attributes or prefix with on props.
5      id="foo"
6      propsOnCustomEvent={this.customEventHandler}
7      // DOM properties are prefixed with `domProps`
8      domPropsInnerHTML="bar"
9      // event listeners are prefixed with `on` or `nativeOn`
10      onClick={this.clickHandler}
11      nativeOnClick={this.nativeClickHandler}
12      // other special top-level properties
13      class={{ foo: true, bar: false }}
14      style={{ color: 'red', fontSize: '14px' }}
15      key="key"
16      ref="ref"
17      // assign the `ref` is used on elements/components with v-for
18      refInFor
19      slot="slot">
20    </div>
21  )
22}

Component Tip

If a custom element starts with lowercase, it will be treated as a string id and used to lookup a registered component. If it starts with uppercase, it will be treated as an identifier, which allows you to do:

1import Todo from './Todo.js'
2
3export default {
4  render (h) {
5    return <Todo/> // no need to register Todo via components option
6  }
7}

JSX Spread

JSX spread is supported, and this plugin will intelligently merge nested data properties. For example:

1const data = {
2  class: ['b', 'c']
3}
4const vnode = <div class="a" {...data}/>

The merged data will be:

1{ class: ['a', 'b', 'c'] }

Vue directives

Note that almost all built-in Vue directives are not supported when using JSX, the sole exception being v-show, which can be used with the v-show={value} syntax. In most cases there are obvious programmatic equivalents, for example v-if is just a ternary expression, and v-for is just an array.map() expression, etc.

For custom directives, you can use the v-name={value} syntax. However, note that directive arguments and modifiers are not supported using this syntax. There are two workarounds:

1. Pass everything as an object via value, e.g. v-name={{ value, modifier: true }}

2. Use the raw vnode directive data format:

1const directives = [
2  { name: 'my-dir', value: 123, modifiers: { abc: true } }
3]
4
5return <div {...{ directives }}/>