https://github.com/victorqueiroz/halter
Simple JS router with support for HTML5 history
https://github.com/victorqueiroz/halter
convenience halter html5-history js-router labeled-routes react
Last synced: about 2 months ago
JSON representation
Simple JS router with support for HTML5 history
- Host: GitHub
- URL: https://github.com/victorqueiroz/halter
- Owner: VictorQueiroz
- License: mit
- Created: 2017-11-07T14:28:43.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2023-01-03T18:23:27.000Z (over 2 years ago)
- Last Synced: 2025-04-03T09:49:22.882Z (about 2 months ago)
- Topics: convenience, halter, html5-history, js-router, labeled-routes, react
- Language: TypeScript
- Size: 385 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# halter 
Simple independent JS router
### Usage
First remember to install `history` NPM module of your choice:
```
npm install history
```
Then set up your routes:
```ts
import { createMemoryHistory } from 'history';
import { Router } from 'halter';
async function bootstrap() {
const router = new Router(createMemoryHistory()).addRoute({
path: '/',
callback() {
// it will be triggered when the browser history match "/"
}
});
// very important to listen to changes on history
await router.init();
// Stop listening to changes on history
router.destroy();
}
```
### Labeled routes
Following an similar approach of Angular UI for Angular 1.x we decided to create labeled routes for convenience, so we can build our app based on labeled routes and not on routes paths it self. For example when you create your `` in your React app instead of putting the path to go when the user click the component, you put a convenient label which will match to be the path you need, check the following example:
```ts
import { createBrowserHistory } from 'history';
import { Router } from 'halter';
import PostDetail from './components/PostDetail';
import PostsList from './components/PostsList';
import Link from './components/Link';
const router = new Router(createBrowserHistory()).addRoute({
name: 'post.detail'
path: '/posts/{id:[0-9]+}',
callback: ({ params }) => {
ReactDOM.render(
,
document.getElementById('app'));
}
}).addRoute({
name: 'post.list',
path: '/posts/list',
callback: () => {
ReactDOM.render(
posts.map(post => (
{post.title}
))}
, document.getElementById('app'));
}
});
router.pushState('post.detail', new Map().set('id', '1040'));
```
The advantages I see on this approach is that you don't need to keep track of paths itself but the route labels instead. So if you need to change a route path you'll be able to do this without worrying about looking all over through your code searching for that path.
Remember that whenever you don't name your route definitions, it'll be the route path (i.e. if you have /posts/{id:[0-9]+} with no name, the name will automatically be /posts/{id:[0-9]+}).
### Listening to changes
Listening to changes on history API it's pretty simple.
```js
const router = new Router();
router.listen((name, params, query) => (
console.log('New path is %s, params are %o and query is %o', name, params, query);
));
```
### Integration with React
Integration with React it's pretty straightforward. You use `` from `react-halter` NPM module and it'll automatically create necessary routes according to the nested structure provided through `routes` property. See the steps below:
1. Install `react-halter` module:
```
npm install --save react-halter
```
2. Set up routes:
```ts
const routes = [{
path: '/',
name: 'app',
component: HomeWrapper,
childRoutes: [{
name: 'post',
path: 'posts/{id:[A-z0-9]+}',
component: Post
}, {
path: 'login',
name: 'login',
component: Login
}]
}, {
name: 'dashboard',
path: '/dashboard',
component: Dashboard,
onBefore: rules.isGuest
}];
ReactDOM.render(
,
document.getElementById('app')
);
```