Migration from riot 2

General info

Riot 3 is a big improvement over the previous release, please check release notes for details.

We have resolved many problems and they required a major release bump because they couldn’t be fixed with the previous codebase. Migration from Riot 2 shouldn’t be very difficult. Refer to the list of breaking changes below.

Breaking changes

riot-tag attribute renamed to data-is

<!-- not supported -->
<div riot-tag="my-tag"></div>

<!-- good -->
<div data-is="my-tag"></div>

Notice that data-is can also be used in nested tags and supports dynamic expressions:

<my-tag>
  <div data-is={ subComponent }></div>

  <script>
    this.subComponent = 'child-tag'
  </script>
</my-tag>

name and id attributes no longer create references to DOM nodes

The name and id attributes are no longer used by riot to cache DOM references to the tag context or add custom tag references to this.tags. Use the ref attribute instead to get references to DOM nodes or custom tags.

Warning: the refs object is only populated after the mount event.

<my-tag>
  <p ref="paragraph">Hello</p>
  <sub-tag ref="childtag"></sub-tag>
  <script>
    this.on('mount', function() {
      console.log(this.refs.paragraph) // => p node
      console.log(this.refs.childtag) // => sub-tag tag
    })
  </script>
</my-tag>

Changed object loop syntax

Object loops now use a different syntax, before we used key, value in object, and now we switched to value, key in object related issue

riot.route removed from riot core

riot.route was removed from riot core to decrease the bundle size in case you choose a different routing library. riot-route is still maintained and can be used with riot or standalone.

No update and updated events triggered before the mount event

Previously riot was firing update and updated events even before the mount event was triggered. Now you can use before-mount and mount to mount your tags properly, the update and the updated events will only be fired on consequent update calls.

Removed automatic preventDefault

Riot 2 was automatically calling event.preventDefault() on any tag event, we thought this behavior was wrong and we decided to remove it.

<my-tag>
  <form onsubmit={ ajaxSubmit }>
    <input>
  </form>

  <script>
    ajaxSubmit(event) {
      // in riot2 this was not needed
      event.preventDefault()
    }
  </script>
</my-tag>

No more parent tag updates on events generated by custom children tags

In riot 2 events generated by custom children tags in loops were triggering an update on the parent as well riot/1319. In riot 3 if you need to update the parent from a custom looped child tag you will need to do it explicitly.

Removed support for spaced events in riot.observable

We made riot.observable 6x times faster than the previous release, but to achieve this performance we had to remove spaced events support. Listening to * is still supported.

var el = riot.observable()

// not supported
el.on('start stop', function() { /* */ })
el.trigger('start stop')

// use this instead
function cb() {}
el
  .on('start', cb)
  .on('stop', cb)

el
  .trigger('start')
  .trigger('stop')

jQuery DOM events

Previously you could trigger riot event handlers via jQuery using $('.my-element').trigger('click'). This was possible because riot 2 was using the old DOM events model ( level 2 ) fully compatible with the jQuery events API. With riot 3 we have upgraded the riot internal events handlers to the more standard new DOM events model level 3 that is not supported by the jQuery DOM events API. This means that you need alternative solutions to the simulate fake events more info.

Scoped css by default

In riot 3 all css rules declared inside a tag’s <style> element are scoped by default and you will no longer need the scoped attribute. There is no option to disable this behavior at the moment.

Deprecated babel 5.8

Now the es6 parser will use the latest babel version more info. You can still manually configure your es6 parser to use the old babel releases. Note that we also support bublé as an alternative to babel.

Template errors are no longer silently swallowed

In riot 2 a handler function had to be manually configured to catch errors in tag templates. In riot 3 all template errors are output using console.error if the console api is available. This is not really a breaking change, because a custom riot.util.tmpl.errorHandler will still work.

All value attributes using expressions will be output as riot-value (riot/1957)

<my-tag>
  <!-- The value attribute will be compiled to riot-value in riot 3. -->
  <input-wrapper value={total} />
  <script>
    this.total = '$11'
  </script>
</my-tag>

<input-wrapper>
  <script>
    // riot3
    console.log(opts.riotValue)
    // riot2
    console.log(opts.value)
  </script>
</input-wrapper>