Getting Started

yarn add retil-router

• Read the 2-minute primer

• View the API reference »

2-minute primer

Your router just is a function.

With retil-router, a router is a function that maps a request to an element.

type RouterFunction = (request: RouterRequest) => ReactNode

You've seen this before -- its a lot like a React component.

const router = request => {
  switch (request.pathname) {
    case '/':
      return <h1>Home</h1>

    case '/about':
      return <h1>About</h1>

    default:
      return <h1>Not Found</h1>
  }
}

Once you have a router function, just pass it to useRouter to get your route -- your current route's content is available on the content property.

import { useRouter } from 'retil-router'

export default function App() {
  const route = useRouter(router)
  return route.content
}

Routers-as-functions is the underlying secret that makes retil-router so powerful. Most of the time though, it's easier to let retil-router create the router functions for you. For example, the above router could be created with routeByPattern().

import { routeByPattern } from 'retil-router'

const router = routeByPattern({
  '/': <h1>Home</h1>,
  '/about': <h1>About</h1>
})

If you want to use retil-router's built in <Link> component and redirect routes, you'll need to make sure they can access the current route and navigate() function. You can do this by wrapping your app with a <RouterProvider>.

import { RouterProvider, useRouter } from 'retil-router'

export default function App() {
  const route = useRouter(router)
  
  return (
    <RouterProvider value={route}>
      {route.content}
    </RouterProvider>
  )
}

Naturally, your route.content element can be nested inside other elements. This lets you easily add layout elements -- like a site-wide navigation bar. And hey presto -- you've now built a simple app with push-state routing!

View this example live at CodeSandbox »

import { Link, RouterProvider, useRouter } from 'retil-router'

function AppLayout({ children }) {
  return (
    <>
      <header>
        <Link to="/">Home</Link>
        <Link to="/about">About</Link>
      </header>
      <main>
        {children}
      </main>
    </>
  )
}

export default function App() {
  const route = useRouter(router)
  
  return (
    <RouterProvider value={route}>
      <AppLayout>
        {route.content}
      </AppLayout>
    </RouterProvider>
  )
}

API Docs

Components

• <Link>
• <RouterProvider>

Hooks

• useLink()
• useMatch()
• useRequest()
• useRouter()
• useRouterController()

Router function helpers

• routeAsync()
• routeByPattern()
• routeLazy()
• routeNotFound()
• routeNotFoundBoundary()
• routeRedirect()

Functions

• createHref()
• getInitialStateAndResponse()
• parseAction()
• resolveAction()

Types

• RouterAction
• RouterController
• RouterFunction
• RouterRequest
• RouterResponse
• RouterState

License

MIT License, Copyright © 2020 James K. Nelson