Adapters

React Native

@stone-js/react-native-adapter makes a phone a context like any other. It captures native causes, a launch, a deep link, an in-app navigation, normalises them into incoming events, and hands the resolution back to the renderer. Paired with use-react-native it runs your pages as screens.

#Install & enable

terminalbash

npm i @stone-js/react-native-adapter @stone-js/use-react-native react-native-url-polyfill

app/Application.tsdeclarativeimperative

import { Routing } from '@stone-js/router'
import { StoneApp } from '@stone-js/core'
import { UseReactNative } from '@stone-js/use-react-native'
import { ReactNative } from '@stone-js/react-native-adapter'

@Routing()
@ReactNative()      // run on a phone
@UseReactNative()
@StoneApp({ name: 'tasks' })
export class Application {}
import { routerBlueprint } from '@stone-js/router'
import { defineStoneReactNativeApp } from '@stone-js/use-react-native'
import { reactNativeAdapterBlueprint } from '@stone-js/react-native-adapter'

export const Application = defineStoneReactNativeApp(
  { name: 'tasks' },
  [routerBlueprint, reactNativeAdapterBlueprint]
)

babel.config.jsjs

module.exports = function (api) {
  api.cache(true)
  return {
    presets: [
      ['babel-preset-expo', { decorators: { version: '2023-11' } }]
    ]
  }
}

#What it captures

Option	Type	Description
launch	`on start`	The URL the application was opened with, or `/` when it was opened plainly. Every run therefore begins with a resolved route.
deep link	`while running`	A URL with your own scheme, `myapp://tasks/42`, matched by the router like any other path.
in-app navigation	`from a screen`	`useNavigate()` goes through the router, so a screen never renders another screen itself.

All three arrive as the same kind of event a browser application receives, which is why the pages, the middleware and the loaders are unchanged. What the adapter never does is decide what a resolution looks like: that is the renderer's job, and the split is the same one every Stone.js platform is built along.

#Deep links

Declare your scheme in app.json and the adapter does the rest: the launch URL and every later link are read through React Native's own linking module and dispatched.

app.jsonjson

{
  "expo": {
    "scheme": "myapp"
  }
}

myapp://tasks/42 then reaches the page that owns /tasks/:id, with 42 readable through event.get('id'). A query string works as it does anywhere else.

#The entry point

One boot, one root component. The module list comes from a file the build generates, which is explained on the native screens page.

index.tsts

// Platform polyfills first, before anything from Stone.js loads.
import 'react-native-url-polyfill/auto'

import { stoneApp } from '@stone-js/core'
import { registerRootComponent } from 'expo'
import { modules } from './.stone/modules'
import App from './App'

void stoneApp({ modules }).run()

registerRootComponent(App)

#Configuration

Option	Type	Default	Description
stone.reactNative.navigationSource	`NavigationSource`	·	The source of navigation events. Supply your own to drive the application from a test, or to change the base URL its links are resolved against.
baseUrl	`string`	`stone://app`	The origin a scheme-less path is resolved against when building the event. Set it to your own scheme so a generated link matches what the platform delivers.

#Running and shipping

#In development

stone dev native collects your modules and hands over to Expo, so there is one vocabulary across platforms. Running npx expo start directly works exactly as well, and still collects them: that part lives in the Metro configuration rather than in the command.

terminalbash

stone dev native            # then press i for iOS, a for Android
npx expo start --web        # the same app in a browser tab, with Fast Refresh

#For production

stone build native produces a Hermes bytecode bundle per platform. Producing an installable application stays npx expo run:ios or an EAS build, which need a native toolchain and are better commands than a wrapper around them would be.

terminalbash

stone build native --platform ios   # a Hermes bundle
npx expo run:ios                    # an installable build, locally
eas build --platform ios            # or in the cloud