Cross-Platform Navigation + Routing

Table of Contents:

• Making routes portable
• Adding page routes
• <Link/>
• useRouter()

Workspace Defined Routes

We strongly recommend you define routes on the workspace level.

This way you can:

• ✅ Colocate routes with the rest of a feature’s domain (maximizes copy-paste-ability)
• ✅ Reuse across platforms (auto re-exported to @app/expo and @app/next)

features/@some-feature
 
 └── /components/...
 └── /screens/... # <- Reuses components
      └── /HomeScreen.tsx
 └── /routes/... # <- Reuses screens
     └── /index.ts # <- Reuses e.g. 'HomeScreen.tsx'

For an example of what this might look like in an actual project, check the example below. Don’t hesitate to click open some of the folders to get a better idea of how the routes are structured:

The recommended and easiest way to create a new route in a workspace is to use the Route Generator:

Using the Route Generator

npm run add:route

The turborepo route generator will ask you some questions, like which url you’d like the route to have, and will generate the empty screens and routes folders in the workspace of your choosing, e.g.:

>>> Modify "your-project-name" using custom generators
 
? Where would you like to add this new route? # (Use arrow keys)  
❯ features/@app-core  --  importable from: '@app/core' 
  features/@some-feature  --  importable from: '@app/some-feature' 
  features/@other-feature  --  importable from: '@app/other-feature'

⬇⬇⬇

>>> Modify "your-project-name" using custom generators
 
? Where would you like to add this new route? # -> features/@app-core
? What should the screen component be called? # -> NewRouteScreen
? What url do you want this route on? # e.g. "/examples/[slug]"
? Would you like to fetch initial data for this route from a resolver? # No data fetching
 
>>> Changes made:
  • /features/@app-core/screens/NewRouteScreen.tsx # (add)
  • /features/@app-core/routes/examples/[slug]/index.tsx # (add)
 
>>> Success!

We’ll be ignoring Data Fetching for now, but we’ll come back to it in .

Manually adding universal routes

If you prefer to add routes manually, follow the steps below:

// ...
 
/* --- <NewRouteScreen> -------------------- */
 
const NewRouteScreen = (props: ...) => {
 
    // ...
}
 
/* --- Exports ----------------------------- */
 
export default NewRouteScreen
 

 
export { default } from '@app/core/screens/NewRouteScreen'
 
// -i- Export any other next.js routing config here
export const dynamic = 'auto'
export const dynamicParams = true
export const revalidate = false
export const fetchCache = 'auto'
export const runtime = 'nodejs'
export const preferredRegion = 'auto'
export const maxDuration = 5
 

npm run collect:routes

Navigating pages

You can navigate using the useRouter hook or Link component from @green-stack/navigation. They provide familiar APIs to how navigation works in both the Next.js and expo-router app routers.

While they use each platform’s underlying navigation system, they are not limited to just expo-router or next.js

Universal useRouter() hook

import { useRouter } from '@green-stack/navigation/useRouter'

You can use router.push() to navigate to a new page:

const router = useRouter()
 
router.push('/examples/[slug]', '/examples/123')

.push() will use a push operation on mobile if possible.

There are also other methods available on the router object:

• router.navigate() - Navigate to the provided href
• router.replace() - Navigate without appending to the history
• router.back() - Go back in the history
• router.canGoBack() - Check if there’s history that supports invoking the back function
• router.setParams() - Update the current route query params without navigating

Universal <Link/> component

If you import the Link component from @green-stack/navigation, it will automatically use the correct navigation system for the platform you are on.

import { Link } from '@green-stack/navigation'

However, you can also import it from @app/primitives to apply tailwind styles:

import { Link } from '@app/primitives'

You can use the href prop to navigate to a new page:

<Link
    className="text-link p-2 rounded"
    href="/examples/[slug]"
>
    See example
</Link>

UniversalLinkProps

Further reading

From our own docs:

• Building APIs
• Universal Data Fetching

Relevant external docs:

• Next.js Route segment config - Determine rendering & caching strategy per route
• Next.js Route Handlers - Used for Data Resolvers and API’s
• Expo Router and React Navigation - Used under the hood on mobile