Lirouter is a lightweight JavaScript routing library used for building static Single Page Applications (SPA).
This library has no dependencies and was made to be light and fast.
This is a guide on how to get started with lirouter. For the documentation, see below Documentation.
First, create an HTML file and import the lirouter script.
Make sure it is imported with
type="module
.
<script type="module" src="/scripts/lirouter.js"></script>
Next, create a script (usually called routes.js) and import it after lirouter.js.
Make sure it is also imported with
type="module
.
<script type="module" src="/scripts/lirouter.js"></script>
<script type="module" src="/scripts/routes.js"></script>
Now, add some buttons with unique IDs.
<button id="home">Home</button>
<button id="about">About</button>
<button id="contact">Contact</button>
Finally, add a container.
<div id="contentDiv"></div>
The file should look like this:
<html>
<head>
<title>Getting started</title>
</head>
<body>
<button id="home">Home</button>
<button id="about">About</button>
<button id="contact">Contact</button>
<div id="contentDiv"></div>
</body>
<script type="module" src="scripts/lirouter.js"></script>
<script type="module" src="scripts/routes.js"></script>
</html>
Import route
, render
and navigate
from lirouter.js.
import { route, render, navigate } from "./lirouter.js";
Add routes to your liking. Let's stick with just a few for now.
route("/", params => {
document.getElementById("contentDiv").innerHTML = "<h1>This is the root path.</h1>";
});
route("/about", params => {
document.getElementById("contentDiv").innerHTML = "<h1>about</h1>";
});
route("/contact", params => {
document.getElementById("contentDiv").innerHTML = "<h1>contact</h1>";
});
route("*", params => {
document.getElementById("contentDiv").innerHTML = "<h1>There is no route for this. 404</h1>";
});
Now, render the page when the document first loads.
render();
Finally, add events to the buttons that you previously created.
document.getElementById("home").addEventListener("click", () => navigate("/"));
document.getElementById("about").addEventListener("click", () => navigate("/about"));
document.getElementById("contact").addEventListener("click", () => navigate("/contact"));
The file should look like this:
import { route, render, navigate } from "./lirouter.js";
route("/", params => {
document.getElementById("contentDiv").innerHTML = "<h1>This is the root path.</h1>";
});
route("/about", params => {
document.getElementById("contentDiv").innerHTML = "<h1>about</h1>";
});
route("/contact", params => {
document.getElementById("contentDiv").innerHTML = "<h1>contact</h1>";
});
route("*", params => {
document.getElementById("contentDiv").innerHTML = "<h1>There is no route for this. 404</h1>";
});
render();
document.getElementById("home").addEventListener("click", () => navigate("/"));
document.getElementById("about").addEventListener("click", () => navigate("/about"));
document.getElementById("contact").addEventListener("click", () => navigate("/contact"));
You'll need something like live-server.
Make sure you have Node.js installed. Then, install live-server.
npm install -g live-server
Next, go to the folder that contains your project, and open the server.
live-server --port=3000 --entry-file="index.html"
You can choose any port, such as 3000
.
The
--entry-file
argument is important, as it tells the server to replace all missing files withindex.html
.
The local server should work now.
Lirouter contains 4 important functions:
- route: adds a new route
- render: renders the page by using the current path
- navigate: navigates to another path
- option: changes an option
You must manually call the
render
function, once, after adding all the routes. If you don't, the page won't render when it's first loaded.After that, the
navigate
function renders the page automatically.
To add a route, use the route
method.
All routes, except for the "*" wildcard, must start with
/
.
route("/route/goes/here", (params) => {
// params - the route parameters (see below the /:param wildcard).
});
Lirouter supports routes with the following wildcards:
- * - any route (this should be added last)
- /* - anything
- /*text - anything ending with text
- /text* - anything starting with text
- /:param - anything, stores the subroute as a parameter (see below Examples)
* will match anything
/* will match:
- /12345
- /hello
- /foo
but not:
- /
- /1234/5678
- /hello/world
- /foo/bar
/path/* will match:
- /path/1234
- /path/foo
- /path/hello
but not:
- /path
- /path/1234/5678
- /path/foo/bar
- /path/hello/world
/path/*/something will match:
- /path/12345/something
- /path/foo/something
- /path/hello/something
but not:
-/path/12345
-/path/foo/something/bar
/path/*st/t* will match:
- /path/best/thing
- /path/fast/test
but not:
- /path/best/foo
- /path/bar/test
/path/:param1/foo/:param2 will match:
- /path/hello/foo/world (sets the params object to { param1: "hello", param2: "world" })
- /path/foo/foo/bar (sets the params object to { param1: "foo", param2: "bar" })
but not:
- /path/hello/bar/world
- /p/foo/foo/bar
You can navigate through your page with the navigate
function.
Always use the
navigate
function instead ofhref
when navigating through your page.If you navigate to the current path (eg. from /about to /about), the page will not re-render. If you want to override this behavior, use the
forceRedraw
option (see below).
navigate("/path/to/navigate");
You can also navigate to a relative path.
Notice that the first character of the path is not
/
.
navigate("path/to/navigate");
By default, navigate
function will also update the URL. If you don't want the URL to change, you can false
for the updateUrl
parameter (by default, it's true
).
navigate("/path/to/navigate", false)
You can set options by using the option
function (don't forget to import it).
import { route, render, navigate, option } from "./lirouter.js";
option('key', 'value');
Currently, there is only one option:
- forceRedraw: whether or not to re-render the page even if the
navigate
function is called on the same path as the current one (default:false
)
Here's an example:
option('forceRedraw', true);
Note: versions with the suffix R are considered stable releases, while those with the suffix D are considered unstable.
v2.2R - December 23, 2020
v2.1R - July 02, 2019
v2.0R - June 20, 2019
v1.0R - June 20, 2019
Lirouter was created by The Exom Developers. It is licensed under the MIT license.