React Router v2/3

With React Router

In React Router v2/3, there are two ways to define routes. You can either use JavaScript objects or JSX Routes (which React Router converts to JavaScript objects).

Both styles described above define the same route structure for three routes: /, /inbox, and /inbox/:message. Each one of these has a component that will be rendered when it matches. The /inbox/:message route has some methods defined to describe its behavior when the route enters, updates, and leaves.

// JavaScript objects
{
  path: '/',
  component: App,
  indexRoute: Home,
  childRoutes: [
    {
      path: 'inbox',
      component: Inbox,
      childRoutes: [
        {
          path: ':message',
          component: Message,
          onEnter: (next) => {...},
          onChange: (prev, next) => {...},
          onLeave: (prev) => {...}
        }
      ]
    }
  ]
// JSX
<Route path='/' component={App}>
  <IndexRoute component={Home} />
  <Route path='inbox' component={Inbox}>
    <Route
      path=':message'
      component={Message}
      onEnter={next => {...}}
      onChange={(prev, next) => {...}}
      onLeave={prev => {...}}
    />
  </Route>
</Route>

With Curi

Routes in Curi are always JavaScript objects. Like React Router, each route object has a path property that describes the path segments that the route matches. React Router v2/3 uses a custom path matcher, but Curi uses path-to-regexp. You can read learn how to format paths from the path-to-regexp repo.

First, we will define the names and paths for our routes.

Each route must also have a unique name. A route's name will be used for interacting with it. For example, to navigate to a route, you only have to know its name, not its URL.

The biggest difference between the Curi paths and the React Router paths is that with Curi, you never include a forward slash at the beginning of the path. This means that while the root path for React Router is '/', the root path for Curi is ''.

const routes = prepareRoutes([
  {
    name: 'Home',
    path: ''
  },
  {
    name: 'Inbox',
    path: 'inbox',
    children: [
      {
        name: 'Message',
        path: ':message'
      }
    ]
  }
]);

Next, we should add our components to each route. We will ignore the App component that is used in the React Router routes. That is not route specific and will be rendered by our application (assuming we actually need it).

With Curi, the router creates a "response" object when it matches locations. Some of the properties of the response are automatically set based on the location and the matching route. Others can be set by a route. This is done using the respond property, which is a function that returns an object whose properties will be added to the response. For this React application, we want a response's body property to be the React component associated with each route.

import { prepareRoutes } from "@curi/router";

import Home from './pages/Home';
import Inbox from './pages/Inbox';
import Mesage from './pages/Message';

const routes = prepareRoutes([
  {
    name: 'Home',
    path: '',
    respond: () => {
      return {
        body: Home
      };
    }
  },
  {
    name: 'Inbox',
    path: 'inbox',
    respond: () => {
      return {
        body: Inbox
      };
    },
    children: [
      {
        name: 'Message',
        path: ':message',
        respond: () => {
          return {
            body: Message
          };
        }
      }
    ]
  }
]);

We are close to replicating our React Router routes, but we still need to implement the on___ methods for our :message route. With Curi, routes can have a resolve function that is called when the route matches the new location.

With React Router, onEnter is called when the route first matches, while onChange is called when the same route matches a new location (e.g. with new path parameters). onEnter and onChange are nearly the same; the big difference between the two is that onChange will receive the previous props, which could be used to determine which props changed. The functionality for both onEnter and onChange can be covered using a resolve function.

There is no equivalent to onLeave with Curi. If you have something you need this functionality for, please open up an issue in the GitHub repo.

The @curi/router route API documentation covers all of the route properties.

const routes = prepareRoutes([
  {
    name: 'Home',
    path: '',
    respond: () => {
      return {
        body: Home
      };
    }
  },
  {
    name: 'Inbox',
    path: 'inbox',
    respond: () => {
      return {
        body: Inbox
      };
    },
    children: [
      {
        name: 'Message',
        path: ':message',
        respond: () => {
          return {
            body: Message
          };
        },
        resolve(match) { return ... },
      }
    ]
  }
]);

React Router v2/3

React Router uses the Router component to subscribe to location changes. Each time that the location changes, it walks over its routes and determines which route(s!) match.

React Router starts by rendering the root component. In the above router, that is the App. Next, our inbox route also matches, so React Router also renders our Inbox component. Finally, the URI /inbox/test also matches our :message route (which is concatenated with its parents to form the path /inbox/:message), so Message is rendered as well. Each child component is rendered by its parent, so we end up with a component tree that looks something like this:

With this structure, any routes with children will be rendered when one of the children matches. That means that those routes need to know how to render based on what type of match they have. For example, Inbox needs to know how to render for an exact match (the URI is /inbox) and for a partial match (/inbox/test). Also, if the Inbox needs to pass any props to Message, it has to use React.cloneElement, which works but is not the cleanest looking code.

<App>
  <Inbox>
    <Message>
  </Inbox>
</App>

Curi

With Curi, we also need to re-render our application every time that the location changes. We will do this by creating a root Curi component by calling the createRouterComponent function, which comes from the @curi/react-dom package, and passing it our Curi router. While the name of this component is entirely up to you, we will refer to it as the Router here.

The Router will setup an observer on the provided router so that it can re-render your application whenever there is a new response. The Router uses a context provider that makes a response available to other components in the application using the useResponse hook.

The useResponse hook returns an object with two properties:

1. response is the new response object
2. navigation is an object with additional information about the navigation

The router can also be accessed throughout the application using the useRouter hook.

Above, we added respond functions to each route. The functions set React components as the body property of responses. We can now use response.body to render those components.

In the React Router section, we had three components that were rendered: App,Inbox, and Message. With Curi, only the most accurately matched route actually matches. That means that for the URL /inbox/test, the "Message" route will match, but its parent route, "Inbox" will not, so response.body will be the Message component. Unlike React Router, we don’t render Inbox because we did not match the inbox route.

import { createRouterComponent, useResponse } from "@curi/react-dom";

const router = createRouter(browser, routes);
const Router = createRouterComponent(router);

function App() {
  const { response } = useResponse();
  const { body:Body } = response;
  return <Body response={response} />;
}

ReactDOM.render((
  <Router>
    <App />
  </Router>
), holder);

/*
<Router>
  <App>
    <Message />
  </App>
</Router>
*/

const routes = prepareRoutes([
  // ...,
  {
    name: "Not Found",
    path: "(.*)",
    respond() {
      return { body: NotFound };
    }
  }
]);

It was mentioned above that there is no need for the App component with Curi. If you want to have an App component, you can render it either inside of the children function or as a parent of your Router. This can be useful for rendering content that is unrelated to specific routes, like a page header or menu.

Rendering the App inside of the children function is necessary if any of the components rendered by the App are location aware components, since they need to access the Curi router (through React’s context, which the Router provides)

function render({ response }) {
  const { body:Body } = response;
  return (
    <App>
      <Body />
    </App>
  );
}
// or
function render({ response }) {
  const { body:Body } = response;
  return (
    <React.Fragment>
      <Header />
      <Body />
      <Footer />
    </React.Fragment>
  );
}

What about props that you want to send to your route components? Pass them to the Body component that you render. Props can be passed individually, but passing the whole response object is recommended.

function render({ response }) {
  const { body:Body } = response;
  return <Body response={response} />;
}