npm package: @operational/router
Description: Router utility to deal with custom base path
Author: Fabien Bernard
Latest version: 0.0.3

# Operational router

[![npm (tag)](https://img.shields.io/npm/v/@operational/router/latest.svg)](https://www.npmjs.com/package/@operational/router)

The goal of this tiny library is to deal with custom `basePath` in a sub-application.

In the context of Contiamo, every application can be run in standalone mode or be embeded inside a global contiamo product. In the second case, some url params are managed in an higher level, this is exactly what we try to solve with this library. This is our solution to compose "easily" multiple application in one.

Note: If you have a better solution, please tell us :wink: We are always happy to learn something.

<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->

- [Getting started](#getting-started)
- [Architecture setup](#architecture-setup)
- [How to use this lib to compose applications](#how-to-use-this-lib-to-compose-applications)
- [Contributions](#contributions)

<!-- END doctoc generated TOC please keep comment here to allow auto update -->

## Getting started

1. `npm i @operational/router react-router react-router-dom`
1. Follow the Archictecture setup

## Architecture setup

Let's do an example to illustrate the setup of this library:

```tsx
<Router>
  <Route path="/:tenant/:project/pantheon" render={/* ... */} />
  <Route path="/:tenant/:project/hub" render={/* ... */} />
  <Route
    path="/:tenant/:project/labs"
    render={({ history: { push, replace } }) => (
      <OperationalRouterProvider
        basePath="/:tenant/:project/labs/"
        pushState={push}
        replaceState={replace}>
        {({ resolvePath, basePath, pushState }) => {
          /**
           *  Labs application router, relative to the `basePath`
           * - I can use `basePath` to define my `Route` and retrieve `tenant` and `project` from the parent
           * - I can use `<Link to={resolvePath("project")} />` to navigate inside the labs context
           * - I can use `pushState("project")` to navigate programatically
           */
        }}
      </OperationalRouterProvider>
    )}
  />

<Router>
```

Finally, this lib exports `OperationalRouter` and `withOperationalRouter` to have access to the same `resolvePath`, `basePath` and `pushState` anywhere inside my application.

Render function style:

```tsx
const MyPage = () => (
  <Page title="my page">
    <OperationalRouter>
      {({ pushState }) => <button onClick={() => pushState("/")}>Go to labs home</button>}
    </OperationalRouter>
  </Page>
);

export default Page;
```

HOC style:

```tsx
const MyPage = ({ pushState }) => (
  <Page title="my page">{<button onClick={() => pushState("/")}>Go to labs home</button>}</Page>
);

export default withOperationalRouter(MyPage);
```

## How to use this lib to compose applications

In contiamo, every applications expose a component with this shape:

```tsx
export interface MyApplicationProps extends OperationalRouterProps {
  /* custom props if needed to configure the app */
}

export const MyApplication: React.SFC<MyApplicationProps> = props => (
  <OperationalRouterProvider {...props}>
    {({ basePath }) => {
      if (!basePath.includes(":tenantId")) {
        throw new Error("This application need to have ':tenantId' in the basePath")
      }

     return <Switch>
        <Route path={basePath} render={<Home />} />
        <Route path={`${basePath}/projects`} render={<Projects />} />
        <Route path={`${basePath}/users`} render={<Users />} />
      </Switch>
    }
  </OperationalRouterProvider>
);
```

## Contributions

Issues, Pull Requests and extensions are welcome. No question is a silly question. Head on over to issues to see where you could get involved, or to open one that will help us further improve this project.