Citron Navigator is a navigator for React web applications written with Typescript.
Main features:
- Render content based on the current URL.
- Use hooks to get the current route and url parameters from anywhere.
- Easily figure if a route or any of its sub-routes are active.
- Concentrate all route definitions in a single file.
- Automatic serialization/deserialization of variables in the URL.
- Type-safe! No more guessing which route accepts which parameters.
- Context-aware: navigating from /resourceA/{resourceAId} to /resourceA/{resourceAId}/resourceB/{resourceBId} should take onlyresourceBId as a required parameter, resourceAId should be optional in this context.
- Support for modular applications (e.g. Module Federation).
The current solutions for navigating a React web application don't embrace Typescript for a type-safe way of navigating, we normally have
to implement type-safe mechanisms on our own in order to guarantee a navigation will always be performed correctly. Unfortunately, it is
hard to force a developer to always use the "correct way of navigating" that we created locally, creating a big mess over time. Some
times we'd have no type-check at all and it can become very easy to go to page that requires a variable without passing this variable.
Another big problem we faced without typed-navigation was getting the search parameters in a page. How would the developer know what search
parameters the page can receive, where are they defined? How does the programmer make changes to these parameters? What's the correct way
to deserialize the string in the URL?
It can become quite complex to manage url variables in a large application, we needed a library that would take care of this for us, so we
created Citron Navigator.
``yaml`
+ root (/):
+ account (/account):
+ profile: (/profile):
+ changePassword: (/password):
+ billing (/billing):
year: number
+ photoAlbums (/albums):
search: string
year: number
month: number (1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12)
limit: number
page: number
type: string ('ownedByMe' | 'sharedWithMe' | 'all')
+ album (/{albumId}):
limit: number
page: number
+ photo (/{photoId}):
The file above defines that we have 8 routes in our application: root, account, profile, changePassword, billing, photoAlbums, album and
photo.
#### Paths
- root: /
- account: /account
- profile: /account/profile
- changePassword: /account/password
- billing: /account/billing
- photoAlbums: /albums
- album: /albums/{albumId}
- photo: /albums/{albumId}/{photoId}
#### Route parameters
- root, account, profile, changePassword, billing and photoAlbums are pages that don't accept any route parameter.
- album accepts an albumId as a route parameter.photoId
- photo accepts a and an albumId (from the parent) as route parameters.
#### Search parameters
- root, account, profile, changePassword and photo are pages that don't accept any search parameter.
- billing accepts one search parameter: "year", and it must be a number.
- photoAlbums accepts many search parameters, they are:
- search: must be a string;
- year: must be a number;
- month: must be a number and be typed as 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12, not any number;'ownedByMe' | 'sharedWithMe' | 'all'
- limit: must be a number;
- page: must be a number;
- type: must be a string and be typed as , not any string.
- album accepts 2 search parameters:
- limit: must be a number;
- page: must be a number.
`tsx
export const Page = () => {
const [content, setContent] = useState
useNavigationContext((context) => {
context
.when('root', props => setContent(
.when('root.account', props => setContent(
.when('root.account.profile', props => setContent(
.when('root.account.changePassword', props => setContent(
.when('root.account.billing', props => setContent(
.when('root.photoAlbums', props => setContent(
.when('root.photoAlbums.album', props => setContent(
.when('root.photoAlbums.album.photo', props => setContent(
})
return content
}
`
Let's see the implementation for Album which is rendered when the route is root.photoAlbums.album:
` Album {albumId} limit is {limit} page is {page} Go back to albums Check out this picturetsx`
const Album = ({ route, params: { albumId, limit, page } }: ViewPropsOf<'root.photoAlbums.album'>) => (
)
Notice that, from "album", we can easily create a link to "photo" by passing only the photoId, the albumId is implicit.
When creating links or navigating to other pages, the type will always be checked by Typescript. In the example above, if we didn't pass
photoId when creating a link to "photo", we'd get a type error and the code wouldn't build.
Attention: we used the component Link
from Citron Navigator. This is necessary if you're not using hash based URLs (flag --useHash=false). If you are using hash based URLs/#/path
(), then you can safely use a simple a tag instead. Example: Go back to albums.
sh
pnpm add -D @stack-spot/citron-navigator-cli
pnpm add @stack-spot/citron-navigator
`citron-navigator-cli is responsible for generating the code while @stack-spot/citron-navigator is the runtime dependency.Configuration
1. If you're using git, ignore the file generated by the CLI. In .gitignore, add: "src/generated".
2. Create the file navigation.yaml in the root of your project. This file should contain the definition for the routes in your
application as showed in the first code example of this document.
3. This is optional, but to make it easier to import navigation related structures, create an alias to src/generated/navigation.ts. In
your tsconfig.json, add:
`json
"paths": {
"navigation": ["./src/generated/navigation"],
}
`
You should do the same to whatever bundler you're using. In Vite, for instance, you should add the following to vite.config.ts:
`ts
{
resolve: {
alias: {
navigation: resolve(__dirname, './src/generated/navigation'),
},
},
}
`Source code generation
`sh
pnpm citron
`By default it will get the definitions from
navigation.yaml and output the generated code to src/generated/navigation.ts. If you need
to change this, pass the options --src and --out.The navigator uses hash-based URLs by default (/#/route). To change this behavior, you can pass the option
--useHash=false to the command
citron.It's a good idea to call
citron before running the application locally or building, check the example below for Vite:package.json:
`json
{
"scripts": {
"dev": "citron && vite",
"build": "citron && tsc && vite build --mode production",
}
}
``