API · Compiler

On browser

Following methods apply to browsers only. Jump to server section if you want to compile under node or io.js.

riot.compile(callback)

Compile all tags defined with <script type="riot/tag"> to JavaScript. These can be inlined script definitions or external resources that load scripts defined with src attribute. After all scripts are compiled the given callback method is called. For example:

riot.compile(function() {
  var tags = riot.mount('*')
})

You can leave out the riot.compile call and write just:

var tags = riot.mount('*')

but you don’t get to know when external resources are loaded and compiled and the return value is an empty array if you have external scripts. If all scripts are defined on the page then riot.compile step can be left out.

For more details, read the compiler general introduction.

riot.compile(url, callback)

Loads the given URL and compiles all tags after which the callback is called. For example:

riot.compile('my/tags.tag', function() {
  // the loaded tags are ready to be used
})

riot.compile(tag)

Compiles and executes the given tag. For example:

<template id="my_tag">
  <my-tag>
    <p>{greeting}, World!</p>
    this.greeting = 'Hello'
  </my-tag>
</template>

<script>
riot.compile(my_tag.innerHTML)
</script>

After the call you can use my-tag normally.

A tag definition is assumed if the first non- empty character is <, otherwise the argument is taken as URL.

Note: In in-browser tag compilation, script tags are not allowed. The last closing tag defines the start of the script part of a tag.

@returns the compiled JavaScript as string

riot.compile(tag, true)

Compiles the tag and returns it as a string. Only the transformation from the tag to JavaScript is performed and the tag is not executed on the browser. You can use this method to benchmark the compiler performance for example.

var js = riot.compile(my_tag.innerHTML, true)

On server

After npm install riot you can do following:

const riot = require('riot-compiler')
const fs = require('fs')
const tagPath = './src/components/component.tag'
const tagSource = fs.readFileSync(tagPath, 'utf8')
const options = {}


const js = riot.compile(tagSource, options, tagPath)

The compile function takes the tag definition (string) and returns JavaScript (string).

Sourcemaps (experimental)

If you will compile using the sourcemap=true option the compiler will return an object containing code and sourcemap. The current riot compiler doesn’t use a “real parser” so the generated sourcemaps might be inaccurate We will generate better sourcemap results in the next riot major release.

Here you can see how to generate sourcemaps reusing the code of the previous example:

const { code, sourcemap } = riot.compile(tagSource, { sourcemap: true }, tagPath)

Using the sourcemap='inline' option, the compiler will return the compiled code appending inline the generated sourcemap

riot.parsers.css [tagName, css]

Custom parsers that could be used to compile your tags CSS. For example:

riot.parsers.css.myparser = function(tag, css) {
  return css.replace(/@tag/, tag)
}

<custom-parsers>
  <p>hi</p>
  <style type="text/myparser">
    @tag {color: red;}
  </style>
</custom-parsers>

will be compiled to:

<custom-parsers>
  <p>hi</p>
  <style type="text/myparser">
    custom-parsers {color: red;}
  </style>
</custom-parsers>

riot.parsers.js [js, options]

Custom parsers that could be used to compile your tags JavaScript. For example

riot.parsers.js.myparser = function(js) {
  return js.replace(/@version/, '1.0.0')
}

<custom-parsers>
  <p>hi</p>
  <script type="text/myparser">
    this.version = "@version"
  </script>
</custom-parsers>

will be compiled to:

<custom-parsers>
  <p>hi</p>
  <script type="text/myparser">
    this.version = "1.0.0"
  </script>
</custom-parsers>

riot.parsers.html [html]

Custom parsers that could be used to compile your tags HTML.

The predefined parsers are:

html

css

* Only less is available on browsers.

js

Changes in v2.3.0

In previous versions, escaped brackets were preserved, generating incorrect HTML or invalid JavaScript code. This version removes them at an early stage, after passing the tag to the html parser and before the JavaScript code and expressions are sent to the js parser.