https://github.com/pothos-dev/magellan
Simplified navigation for React Native with improved Typescript support, based on react-navigation
https://github.com/pothos-dev/magellan
Last synced: 5 months ago
JSON representation
Simplified navigation for React Native with improved Typescript support, based on react-navigation
- Host: GitHub
- URL: https://github.com/pothos-dev/magellan
- Owner: pothos-dev
- Created: 2019-07-23T18:53:30.000Z (almost 7 years ago)
- Default Branch: master
- Last Pushed: 2024-12-09T23:46:25.000Z (over 1 year ago)
- Last Synced: 2025-04-01T21:42:02.129Z (about 1 year ago)
- Language: TypeScript
- Size: 87.9 KB
- Stars: 2
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# @bearbytes/magellan
This is a wrapper around [react-navigation](https://github.com/react-navigation/react-navigation), the popular navigation library for React Native.
It adds improved Typescript support and a simplified API for basic navigation needs.
# Getting started
Install the dependency:
`npm i @bearbytes/magellan`
Define the available screens and their corresponding navigation parameters:
```typescript
export interface AppScreens {
Home: {}
UserProfile: { userId: string }
Chat: { partnerUserId: string; isPrivate?: boolean }
}
```
Initialize the navigation system. It will create a StackNavigator which can be pre-configured with the usual [configuration](https://reactnavigation.org/docs/en/stack-navigator.html#stacknavigatorconfig):
```typescript
import { createNavigation } from './lib/Magellan/createNavigationRoot'
import { AppScreens } from './AppScreens'
export const {
NavigationRoot,
navigate,
navigateBack,
dispatchNavigationAction,
} = createNavigation({
// Pass configuration for the main StackNavigator here
headerMode: 'none',
transparentCard: true,
})
```
The `NavigationRoot` is a React Component that will contain the currently visible screen(s). Put it into the root of your app. You will need to pass it a component for each screen in the `AppScreens` interface.
```tsx
export default function MyApp() {
return (
{/* Should be the main component */}
{
// You could also create adhoc components in here.
// The props passed to the component are equivalent to
// navigation parameters in react-navigation.
if (props.isPrivate) {
return
} else {
return
}
}}
/>
)
}
```
To avoid having to maintain duplicate props definitions, I would advise to use the `AppScreens` interface to define the screen props:
```tsx
export function UserProfileScreen(props: AppScreens['UserProfile']) {
return Profile of {props.userId}.
}
```
# Navigating
As you may have noticed, the [navigation](https://reactnavigation.org/docs/en/navigation-prop.html) prop that is usually used in `react-nativation` is nowhere to be found here. Instead, `magellan` opts to use top level functions to navigate between screens:
```typescript
// The navigate function knows about which screens exist and
// what parameters can or must be passed to them. Typescript
// will enforce that we never forget something here.
navigate('UserProfile', { userId: 'bob' })
// Navigation params must always be passed, even when empty.
navigate('Home', {})
// Go back to the previous screen.
// Does nothing when there is only one screen on the stack.
navigateBack()
// The above actions should be enough for most usecases.
// If you need to use a more complex action, you can dispatch
// it directly. Note that unlike the other functions, no
// typesafeness is guaranteed here.
dispatchNavigationAction({ type: 'Navigation/OPEN_DRAWER' })
dispatchNavigationAction({
type: 'Navigation/POP_TO_TOP',
immediate: true,
})
```