Releasing today, Navi is a new and ambitious router framework that focuses on solving the complex issue of JavaScript app page routing by handling all the heavy lifting.
With an easy to use API, Navi provides:
  • A first-class React integration
  • Code-splitting
  • Page loading transitions
  • Generated JSON site maps
  • Accessible page title management
  • And more...

Getting Started with Navi

Navi can be attached to an existing React app, or implemented from the beginning with Create React App by running the following command:
npx create-react-app my-navi-project

Creating a new React project called `my-navi-project` under a directory of the same name with Create React App.

After moving into the project directory, you now need to install Navi as a dependency, including the React functions for it:
yarn add navi react-navi

Step 1: Create Some Routes

Within the src directory of our project, create a directory called pages and put an index.js file inside which will be the control center of our routing.
This file uses Navi's createSwitch and createPage APIs to create the routing switch and the pages for each route.
// Import dependencies from navi and react
import { createPage, createSwitch } from 'navi'
import * as React from 'react'
import { NavLink } from 'react-navi'

// Create the switch
export default createSwitch({
  paths: {
    // Create the index route
    '/': createPage({
      title: "Navi",
      content:
        <div>
          <h2>My Navi React Project</h2>
          <p>This is the index route!</p>
          <nav><NavLink href='/about'>See the about page</NavLink></nav>
        </div>
    }),

    // Create the about route
    '/about': createPage({
      title: "About",
      getContent: () => import('./About')
    }),
  }
})

Creating two routes, one for the base path /, and one for the /about URL route.

The next step is to create the About.js file within our pages directory, for which you have already set up a route above.
This page is just a React component:
import * as React from 'react'
import { NavLink } from 'react-navi'

export default function About() {
  return (
    <div>
      <h2>This is the about page</h2>
      <p>This route was compiled and handled by Navi, including all the heavy lifting for SEO, creating sitemaps including this page, code-splitting, etc!</p>
      <nav><NavLink href="/">Back to the index</NavLink></nav>
    </div>
  )
}

A small React component that renders an about page.

Step 2: Create the Navigation

With routes in place, it's time to tell our app how to use them. You can take the src/index.js file that Create React App generates and modify it slightly.
import * as React from 'react'
import * as ReactDOM from 'react-dom'
import { createBrowserNavigation } from 'navi'
import pages from './pages'
import App from './App'

async function main() {
  let navigation = createBrowserNavigation({ pages })

  // Wait until async content is ready.
  await navigation.steady()

  ReactDOM.render(
    <App navigation={navigation} />,
    document.getElementById('root')
  );
}

// Start the app
main()

The index.js file that renders our App.

Step 3: Handle the Navigation in `App.js`

Now that Navi is set up to deal with the navigation, has routes to handle, and our app renders the App component, you need to modify the Create React App generated App.js file to handle our routes inside a layout.
import React, { Component } from 'react';
import { NavProvider, NavRoute, NavNotFoundBoundary } from 'react-navi';
import logo from './logo.svg';
import './App.css';

class App extends Component {
  render() {
    return (
      <NavProvider navigation={this.props.navigation}>
        <div className="App">
          <img src={logo} className="App-logo" alt="logo" />
          <NavNotFoundBoundary render={renderNotFound}>
            <NavRoute />
          </NavNotFoundBoundary>
        </div>
      </NavProvider>
    );
  }
}

const renderNotFound = () => (
  <div className="App-error">
    <h1>404 - Page not found.</h1>
  </div>
)

export default App;

The App.js file that handles the navigation, loads the content for the route and handles a 404.

With the above, Navi's React components NavProvider, NavRoute, and NavNotFoundBoundary all work together to handle navigation based on the currently accessed route.
All of this functionality exists within a layout made with JSX that you have defined above, which wraps around the content of each route.
This is just an example of a basic setup with Navi, but it's API is much more powerful and is built to handle a lot more cases to suit your needs. Visit the documentation for Navi to find out more.
Note: This project omits the included Service Worker that comes with Create React App to be more brief since it is optional. You are free to include this yourself.

Deploying with Now

Now that your Navi project is set up, you need somewhere to place it. Luckily, Now is at our disposal and can be configured to build our app and deploy it very quickly.
If you are not familiar with Now and want to get setup, read our Getting Started guide.

Step 1: Creating a `now.json` file

First, create a now.json file in the root of your project. This will achieve a few things:
{
  "version": 2,
  "name": "my-navi-project",
  "builds": [
    {"src": "package.json", "use": "@now/static-build", "config": { "distDir": "build" }}
  ],
  "routes": [
    {"src": "^/static/(.*)", "dest": "/static/\$1"},
    {"src": "^/favicon.ico", "dest": "/favicon.ico"},
    {"src": "^/manifest.json", "dest": "/manifest.json"},
    {"src": "^/(.*)", "dest": "/index.html"}
  ]
}

A now.json file that handles building your Navi project and routes users depending on specific paths.

Note: You can also statically generate each file with Navi! If you want to deploy multiple static files with a bit more configuration and some SEO benefits, read their Static Rendering guide.

Step 2: Instructing Now to Build

The now.json file just created uses the @now/static-build builder which requires instructions on how to build the app. You can pass this instruction to the builder by creating a now-build script in the package.json file:
{
  "scripts": {
    ...
    "now-build": "yarn build"
  }
}

The addition of a now-build script that instructs Now to build the application using Create React Apps existing build script.

Step 3: Deploy

Finally, the only thing left to do to get our application live is to deploy it with Now:
now

Deploying with Now.

When Now is deploying, it will provide you with a live progress indicator of your build and a link to your deployment, such as the following: https://my-navi-project-448it4kzn.now.sh

Conclusion

Navi is an exciting routing framework that does all the hard work of applying the navigation methods and API for you. We are excited to see this project grow and to see what users do with it.