riot-tagrouter

    npm install --save riot-tagrouter

Riot js comes with a pretty rock solid router along with the library file. This router however is purely imperitive and maintaining it in a large codebase can go out of hand pretty easily.

riot-tagrouter is a declarative wrapper around the same, it uses the same riot router in its core and auto starts the riot router upon its mount.

Motivation

This router aims to expose a more simpler and declarative way to Router for riotjs apps that not only can work super easily out of the box, but also has first class support for lazy loading of the routes and PRPL for app.

API

The API is kept pretty clean and minimal, a minimal router config would be declared as follows:

    <router base-route='/'>
        <route path='/' component='home'></route>
        <route path='/user/:user' component='user-profile'></route>
        <route path='/messages'>
            <route path='/:from-:to' component='msg-component'></route>
            <router path='/..' component={msg-404}/>
        </route>
        <router path='/..' component={tag-404}/>
    </router>

in the above example base-route will be the route base customizable as per the riot router, this sets the root url for your entire app.

This router as promised also has first class support for lazy loaded routes again in a declarative way. The component attribute of the router takes one of the two parameter

1. A string type name of the component to be mounted
2. A function which either returns a string or a promise which at the end needs to be resolved with a string type name of the component

    <router base-route='/'>
        <route path='/' component='home'></route>
        <route path='/user/*' component='user-profile'></route>
        <route path='/messages'>
            <route path='/:from-:to' component={this.parent.parent.getMessegesComponent}></route>
        </route>
    </router>
    .
    .
    .
    <script>
        this.getMessegesComponent = function (){
            return new Promise((resolve,reject){
                //some webpack or require magic here to load the tags now
                resolve('msg-component');
            });
        }
    </script> 

see Lazy Loading your Riotjs SPA for hints on webpack stuff

Custom navigation element

element bundled with this package uses riot.route internally to navigate to any route, for a11y purpose all navigate elements will be '' tags.

    <navigate to='/user/john' title='John' replace={true}>
        <svg>
        .
        .
        .
        </svg>
    </navigate>

Route values to components

The component specified in the route tag(or passed via promise) will recieve all the route params in opts of the component.

e.g. in above example, path '/user/:user' the component 'user-profile' wil recieve an opts 'user' with the route value.

Events

Following two events will be published on 'Router' tag's tag defination(using .trigger) and also via .opts (i.e. 'on-' attributes)

1. Route Changed: Whenever the route is changing a 'routeChange' event will be triggered on the tag implementation and also if a function is passed to 'on-routechange' attribute then that will be called too.
2. Tag not found: Whenever a while mounting a tag is not found a 'tagNotFound' event will be triggered on the tag implementation and also if a function is passed to 'on-tagnotfound' attribute then that will be called too.

Isomorphism

Now obviosly, time to first meaningful paint is the new perf metrics we cannot miss the importance of, hence server rendered streamed HTML is something of utmost importance for riot-tagrouter.

That brings in the need of Isomorphism from the router's side. We aim at making this a super easy process for the users. For server side rendering allow riot.render to inject the your router component into your markup.

    var riot = require('riot');
    var appRoutingTag = require('path to tag which has router implementations');
    //console.log or res.render or how ever u wanna do it
    res.render('index',{
        routerMarkup: riot.render('app-router');//app-router be the name of the tag in which you encapsulate the router tag
    });

For serverside rendering we highly recommend to use the following npm module https://github.com/ilearnio/riot-ssr DEMO cum Docs: prateekbh.github.io/riot-tagrouter

Usage

After NPM installation, inside the node_modules > riot-tagrouter > build will be the routerlib.js(ES5 verison) or router_tags_es6.js(ES6 version), feel free to use the build toold of your choice(Webpack,Grunt, gulp).

Also a raw(Un Rioted and ES6) version of all the tags lie in tags folder if you want a specific loader to precess it for your Webpack.

Note

1. All ':slugs' are replaced by '*' internally, you can however use all the rules that you can use in riot router, however url params will be passed as opts only for ':slug' keys.
2. It is highly recommended to keep your router instance inside another riot tag when you are planning a lazy loading component, it will help you pass component as a function.