@goncharov-vlad/spa-router

JS module which helps to build not reloading web applications.

Usage no npm install needed!

<script type="module">
  import goncharovVladSpaRouter from 'https://cdn.skypack.dev/@goncharov-vlad/spa-router';
</script>

README

SPA-router

JS module which helps to build not reloading web applications.

It's easy to install, configure and use.

A single-page application (SPA) is a web application or website that interacts with the user by dynamically rewriting the current web page with new data from the web server, instead of the default method of a web browser loading entire new pages. The goal is faster transitions that make the website feel more like a native app. [Wikipedia]

Installing / Getting started

Run to get success with installation.

npm i @goncharov-vlad/spa-router

This command is just common way to install JS module.

Initial Configuration

  1. Import module.
import Router from '@goncharov-vlad/spa-router'
  1. Define config object and specify route stack as config property.

Example:

let config =
    {
        'stack': [
            {
                'pathTemplate': '/',
                'action': () => console.log('Home')
            },
            {
                'pathTemplate': '/contact',
                'action': () => console.log('Contact')
            },
            {
                'pathTemplate': '/post/{postId}/comment/{commentId}',
                'action': (values) => console.log(`Comment ${values.commentId} of post ${values.postId}`)
            }
        ]
    }
  1. Create new router instance with defined config.
new Router(config)

That's all.

Features

After configuring the router just use links as usually

When link is clicked, the router matches link path to each path template from route stack and when path template is matched the router executes its action passing data from path as first parameter.

Example:

<a href='/post/11/comment/12'></a>

Imagine you have that link and route with path template /post/{postId}/comment/{commentId} which will be matched after click, and then you will be able to get postId with value 11 and commentId with value 12 inside action callback by first parameter.

Action callback can look like:

(values) => console.log(`Comment ${values.commentId} of post ${values.postId}`)

Of course, to pass data you also can use GET parameters

What's the bells and whistles this project can perform?

  • The router stores all history, that means when client uses next/back buttons of browser the correspond routes will be triggered.

  • Code of the module is very small, and it doesn't use any additional modules, that makes the module fast and simple.

  • The router automatically finds all new dynamically added in DOM links (MutationObserver).

  • You don't have to use old hash style of path.

Full config overview

  • config object parent

    • stack route[] require

      Array of routes

    • notFoundRoute function

      Action which will be executed when route is not found. Default action is () => console.log('not-found')

  • route object

    Specific route

    • pathTemplate string require

      Path by which action will be executed. To pass values use name of value inside curly braces

    • action function require

      Action which will be executed. To get values from path use first param

Contributing

Contributions are always welcome!

Project have to use jsDocs. You also can get full documentation with running jsdoc -r path/to/this/module.

Links

Github - https://github.com/goncharov-vlad/spa-router

Npm - https://www.npmjs.com/package/@goncharov-vlad/spa-router

Licensing

The code in this project is licensed under MIT license.