If you've written any kind of single-page app, you've probably worked with a client-side routing library - you give it different route strings, like /home and /about and maybe /post/:postId, and when one of those routes is visited the routing library calls the right function.

Or maybe if you use AngularJS, you've been lucky enough to use ui-router. ui-router lets you nest multiple "states", so that the URL can change and show you content, but without you having to reload the whole page.

To see it in action, open one of the implementations below and click around the demo app - note how when you click on the different topics, the list of tasks changes - but nothing else in the app has to reload.

If these are too complicated

These are meant to serve as an example of what a "real" application might look like with various rendering engines. They span multiple directories, are built with browserify, have templates in their own file, use local storage, etc.

It uses Ractive's mustache templating, but other than that it's straight vanilla JS all in a single file.

These example todo apps

You can read the docs over on Github, but this site is here to serve as a proof of concept (you really can use a state router what whatever templating library you want!) and give people some code to copy/paste.

These examples use node-style require() calls made possible in the browser with Browserify.

Made with Ractive.js

Ractive.js is my favorite templating/DOM manipulation library at the moment. A simple API that lets you interact with live content in the DOM and gives you the ability to write custom extensions your webapp will need, but gets out of your way for everything else.

Made with Ractive.js + Redux

Redux is a pretty compelling way to manipulate state - by restricting yourself to a pure function that takes in the old state and returns the new state, you gain simplicity, plus some cool features like easy undo/time travel.

Using the sexily-named state-router-redux-ractive library with abstract-state-router, you can associate a reducer function and optional side effects with your routing state. Not every state in the example has a reducer, just the ones involving more "documenty" view state. You can use reducers as you please.

Made with virtual-dom

virtual-dom lets you describe a DOM hierarchy using straight JavaScript, and render the result to the browser. To change the browser's DOM later, use JavaScript to describe the new DOM state, which virtual-dom compares to your original hierarchy, updating the DOM from the previous state to the new state as efficiently as possible.

Want to use a different templating/dom manipulation library?

Do it! That's the point of the state router being abstract - you get powerful routing with whatever templating setup you prefer.

The easiest way to start is probably to fork this example repo and make a new copy of either the riot/ractive folder, and then to copy either the Riot renderer or the Ractive renderer and overwrite the methods with whatever makes sense for your dom manipulation shenanigans.

I will help you

I would love to help other people get their favorite front-end libraries working with the state router. Feel free to open a Github request with any questions, or even just ping me on Twitter.

If you're new to Browserify, I can help you get set up. If you don't want to touch Browserify and would like to help umd-ify the abstract-state-router, I'm open to pull requests - I just don't have any motivation to support non-browserify environments until someone comes along and asks for it.

I'm planning on using the abstract-state-router for my own webapps going forward, but I would be happy to help other people use it. Ask me if you have any questions.