Pre-compilation

The Compilation phase is asynchronous and it will not block your application rendering. However you should use the browser compilation only for prototyping or for quick experiments.

Pre-compilation on gives you following benefits:

• Ability to compile tags with your favorite pre-processor.
• Big performance benefit. No need to load and execute the compiler on browser.
• Sourcemaps support for debugging.

Riot loaders

Tools like webpack and rollup are the perfect match to bundle your riot application tags.For such tools we provide riot official loaders to let import natively riot components into your source code:

• webpack
• rollup
• parcel
• riotifyWith the riot loaders your application entry script might look like this:

import { component } from 'riot'
import MyTag from './path/to/tags/my-tag.riot'
component(MyTag)(document.getElementById('root'))

Compilation via Node

import {compile} from '@riotjs/compiler'
const { code, map } = compile('<p>{hello}</p>', {
  //...options
  file: 'my/path/to/my-component.riot',
  // transform the `:host` css rules
  scopedCss: true,
  // expressions delimiters
  brackets: ['{', '}'],
  // keep HTML comments
  comments: false
})

The compile function takes a string and returns an object containing the code and map keys.You can handle the code generated however you like and use it into your build system.

Remember that the riot compiler outputs javascript modules and you might want to transpile them in your bundle.

Compilation via Riot.js CLI

You can precompile Riot.js files also via the riot executable, which can be installed with NPM as follows:

npm install @riotjs/cli -g

Using

Here is how riot command works:

# compile a file to current folder
riot some.riot
# compile file to target folder
riot some.riot --output some-folder
# compile file to target path
riot some.riot --output some-folder/some.js
# compile all files from source folder to target folder
riot some/folder --output path/to/dist

For more information, type: riot —help

Watch mode

You can watch directories and automatically transform files when they are changed.

# watch for
riot -w src -o dist

Custom extension

You’re free to use any file extension for your tags (instead of default .riot):

riot --extension html

ES6 Config file

You can use a config file to store and configure easily all your @riotjs/cli options and create your custom parsers

riot --config riot.config src

The riot riot.config.js file:

export default {
  output: 'tags/dist',
  // sourcemap type
  sourcemap: 'inline',
  // files extension
  extension: 'foo'
}

If you want to use custom preprocessors in your project you should install @riotjs/cli as devDependency running it via npm scripts as follows:

{
  "scripts": {
    "build": "npx riot -c riot.config src"
  },
  "devDependencies": {
    "@riotjs/cli": "^4.0.0",
    "@riotjs/compiler": "^4.0.0",
    "pug": "^2.0.3"
  }
}

That’s how your riot.config.js file might look like in case you want to use pug as components template engine

import { registerPreprocessor } from '@riotjs/compiler'
import { render } from 'pug'
// register the pug preprocessor
registerPreprocessor('template', 'pug', (code, options) => {
  const { file } = options
  return {
    code: render(code, {
      filename: file,
      pretty: true,
      doctype: 'html'
    })
  }
})
export default {
  extension: 'pug',
  // assign the pug preprocessor to the riot compiler options
  riot: {
    template: 'pug'
  }
}

Build your whole application

You can also use the CLI to bundle your entire application.

The app.js file:

import {component} from 'riot'
import App from './app.riot'
component(App)(document.getElementById('root'))

riot app.js -o dist/app.js

Your dist/app.js file will contain all the Riot.js components imported in your application and the code to run it.