Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/bitttttten/oatmilk
Minimal routing library for React.
https://github.com/bitttttten/oatmilk
es6 hooks react reactjs router routing
Last synced: about 1 month ago
JSON representation
Minimal routing library for React.
- Host: GitHub
- URL: https://github.com/bitttttten/oatmilk
- Owner: bitttttten
- License: mit
- Created: 2019-04-27T18:42:10.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2022-12-09T21:36:37.000Z (about 2 years ago)
- Last Synced: 2024-11-03T07:25:06.151Z (about 2 months ago)
- Topics: es6, hooks, react, reactjs, router, routing
- Language: TypeScript
- Homepage:
- Size: 5.46 MB
- Stars: 35
- Watchers: 2
- Forks: 0
- Open Issues: 17
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# oatmilk
[](https://github.com/prettier/prettier)
[](https://github.com/bitttttten/oatmilk/releases)
[](https://github.com/bitttttten/oatmilk/compare/v3.2.1...master)
[](https://www.npmjs.com/package/oatmilk)
## Introduction
oatmilk is a minimal routing library for React.
## Docs
- [Server rendering](https://github.com/bitttttten/oatmilk/blob/master/docs/server-rendering.md)
- [Typescript](https://github.com/bitttttten/oatmilk/blob/master/docs/typescript.md)
- [Using Context](https://github.com/bitttttten/oatmilk/blob/master/docs/using-context.md)
## Instructions
### Install
`yarn add oatmilk`
### Wrap your App with your routes
Each route is an object with the required shape:
```sh
{
name: string
path: path
view: ReactNode
onEnter?: function
onBeforeExit?: function
}
```
Where `path` is any default pattern of [url-pattern](https://www.npmjs.com/package/url-pattern). The 2 optional properties `onEnter` and `onBeforeExit` are explained in the [transition hooks docs](https://github.com/bitttttten/oatmilk/blob/master/README.md#transition-hooks).
You must included a route with a name of `notFound` since this is the fallback route. The order of the routes does not matter.
```js App.tsx
import oatmilk from 'oatmilk'
const routes: oatmilk.IRoute[] = [
{
name: 'home',
path: '/',
// send in any react node
view: () =>
The world never says hello back..
,
},
{
name: 'user',
// 'named segment'
path: '/user/:id',
// use React.lazy to help with code splitting
view: React.lazy(() => import('./Pages/User.tsx')),
},
{
name: 'notFound',
path: '/404',
// or use @loadable/component for SSR support
view: loadable(() => import('./Pages/NotFound.tsx')),
},
]
ReactDOM.render(
,
document.getElementById('root'),
)
```
### Render a RouterView
The `RouterView` will render the current route's `view`.
```js App.tsx
export function App() {
return (
<>
>
)
}
```
### Render some links
No need to generate the paths here, oatmilk will find the route and generate a path for you that is derived from the state.
```js App.tsx
function Navigation() {
return (
<>
Go home
Go to my page
>
)
}
```
..and off you go 🎉✨
## API
## useOatmilk
oatmilk has a React hook `useOatmilk` that provides routing utilities and information about the current route.
It returns the interface `oatmilk.IContext` which is:
```js
{
// used to to change routes
goTo: (toRouteName: string, toState?: object) => void
// used to generate the href of a link element of a route
getHref: (routeName: string, state?: object) => string
// information about the current route
route: {
name: string
path: string
view: ReactComponent
}
// the current state object
state: object
}
```
### Transition Hooks
oatmilk has 2 transition hooks: onEnter, and onBeforeEnter. You can use it for the global routing context, and also for a single route's context.
```js routes.tsx
import oatmilk, { IRoute, TRouteState } from 'oatmilk'
export const routes: IRoutes = [
{
name: 'home',
path: '/',
view: HomePage,
onEnter: (route: IRoute, state: TRouteState) => {
console.log('I am called as you enter only the home route')
ArticlesStore.fetchTrendingArticles()
TodoStore.fetchTodos()
},
onBeforeExit: (route: IRoute, state: TRouteState) => {
console.log('I am called as you exit only the home route')
},
},
{
name: 'user'
path: '/user/:slug',
view: UserPage,
onEnter: (route: IRoute, state: TRouteState) => {
UserStore.fetchUserById(state.id)
},
},
]
function onEnter(route: IRoute, state: TRouteState) {
console.log('I am called as you enter any route')
analytics.logPageView()
}
function onBeforeExit(route: IRoute, state: TRouteState) {
console.log('I am called as you exit any route')
}
ReactDOM.render(
,
document.getElementById('root'),
)
```
### Hook callee
oatmilk ships with a way to customise how the above hooks are called with a `hookCallee` function. Use this method to inject your own callee to completely customise the transition hooks. This can help with server side rendering by passing in a store on the server and client. Learn about that in [the server rendering docs](https://github.com/bitttttten/oatmilk/blob/master/docs/server-rendering.md).
## Decoupled
oatmilk is state first, and everything else is derived from this. The current route is held in state and effects like updating the URL, are managed after the fact. Decoupling your state and data fetching from your view helps you keep a declarative approach to your codebase. It also makes reasoning and testing simplier, and greatly reduces the complexity of server rendering and pre-fetching data.
## Credits
Thanks to [probablyup](https://github.com/probablyup)'s [buttermilk](https://github.com/probablyup/buttermilk), which was a project I found after writing the first draft of oatmilk which inspired a lot of changes and inspiration.. and of course the name.
Made possible by
