epic-router
v6.1.0
Published
Router for the Web and React Native.
Downloads
250
Readme
epic-router
Router for the Web.
- Navigate between different screens
- Handles browser history
- Supports back and forward button
- 404 error page
- See reactigation for a React Native router
Installation
bun install epic-router
# Install a JSX rendering framework.
bun install epic-jsx / bun install preact
Usage
import { Page, addPage, back, configure, go, forward } from 'epic-router'
import { connect } from 'epic-state/connect'
import { render } from 'epic-jsx'
const { router } = configure<{ id: number }>('overview', undefined, undefined, connect)
// Declare some components used as pages.
const Overview = () => <p>Overview</p>
const About = () => <p>About</p>
const Article = () => <p>Article: {router.parameters.id}</p>
addPage('overview', Overview)
addPage('nested/about', About)
addPage('article', Article)
// Custom 404 page for missing routes.
addPage('404', () => <p>Not found!</p>)
render(
<div>
<button onClick={() => Router.go('nested/about')}>About</button>
<button onClick={() => Router.go('article', { id: 2 })}>Article 2</button>
{/* Currently active page will be displayed in Page component. */}
<Page />
</div>
)
<Page />
import { Page } from 'epic-router'
Use the <Page />
component anywhere in your layout to display the current page. Any props you pass to it will be handed over to the page components themselves:
<Page onError={(error) => console.error(error)} />
Router
import { configure, addPage, go, back, forward, initial } from 'epic-router'
// Setup and configure the Router.
const { router } = configure(initialRoute?: string, homeRoute?: string, initialParameters?: Parameters, connect?: typeof preactConnect)
// Register a page for a route.
addPage(route: string | number, component: JSX | ReactNode)
// Navigates to a route. Parameters will be added to the URL search query and together with the state (both optional) will be passed to the page component as props. If replace is true, `back()` will not lead to the previous page.
go(route: string, parameters: object = {}, state: object = {}, replace = false)
// go back one step in the history.
back()
// Go forward one step in the history.
forward()
// Go to the initial route.
initial()
// Currently active route.
Router.route => string
// Parameters for current route.
Router.parameters => Object
// Initial route.
Router.initialRoute => string
// Available routes.
Router.pages => Object
// Underlieing history object, either BrowserHistory or MemoryHistory.
Router.history => History
Error Route (404 Not Found)
The 404
page can be set to show a custom error page when a route is not found.
import { addPage } from 'epic-router'
const Custom404 = () => <p>Page Not Found!</p>
addPage(404: Custom404)
Parameters
Parameters will automatically be added to the URL and are accessible in different ways as shown below.
import { configure, getRouter, type WithRouter } from 'epic-router'
type Parameters = { id: number }
const { router } = configure<Parameters>(...)
const Article = () => <p>Article: {router.parameters.id}</p>
const ArticleGlobal = () => <p>Article: {getRouter().parameters.id}</p>
const ArticleProps = ({ router }: WithRouter<Parameters>) => <p>Article: {router.parameters.id}</p>
Notes
If process.env.PUBLIC_URL
is set during build the path will be adapted accordingly. This router assumes an SPA (Single Page Application) environment on the server. For initial URL requests to arrive at the router the server has to be instructed to rewrite requests to the index. See Legacy SPA Fallback on how to configure this for Vercel in vercel.json
.