@stone-js/react-native-adapter

React Native adapter for Stone.js. Runs your domain as a native mobile application, with Expo or bare React Native.

Overview

This is the Integration dimension for a phone. It captures what a native application can be asked (the URL it was launched with, deep links delivered while it runs, navigation from inside the app), turns each one into the same IncomingEvent your handlers already receive, and runs the render effect the view layer deferred.

The domain does not change. A handler that answers /tasks/:id behind an HTTP adapter answers the same route when a push notification opens myapp://tasks/42, and nothing in it knows the difference.

Key Features

• Deep links, for free: the launch URL and every later link resolve through your router, so myapp://tasks/42 reaches the handler that owns /tasks/:id.
• One navigation loop: router.navigate('/tasks') from a screen re-enters the kernel exactly like a link would, with no History API anywhere.
• The same event as the browser: an IncomingBrowserEvent, so pages and middleware move between web and native untouched.
• Testable without a device: the platform's linking module is resolved, not imported, so the whole chain runs under a plain Node test runner.
• Zero configuration: in-app paths resolve against stone://app, cookies are kept in memory, and react-native is never imported statically.

Installation

npm i @stone-js/core @stone-js/browser-core @stone-js/react-native-adapter

Inside a React Native application, so react-native is already there. It is deliberately not a peer dependency: this package never imports it statically (deep links are resolved at runtime, and their absence is a supported case), and declaring it would pull the whole Metro toolchain into every workspace that merely builds against this package, for a requirement no real application can fail to meet.

React Native's URL is a stub without a usable pathname, which the router needs on every event, so a polyfill is required before anything from Stone.js loads:

npm i react-native-url-polyfill

// index.ts, first line
import 'react-native-url-polyfill/auto'

Stone.js runs on TC39 2023-11 decorators. babel-preset-expo applies the decorators plugin itself, in legacy mode by default, so ask it for the standard semantics rather than adding the plugin separately:

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

Usage

Enable it the declarative way, with its decorator:

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

@Routing()
@ReactNative()
@StoneApp({ name: 'my-app' })
export class Application {}

Or the imperative way, with its blueprint:

import { defineStoneApp } from '@stone-js/core'
import { reactNativeAdapterBlueprint } from '@stone-js/react-native-adapter'

export const Application = defineStoneApp(handler, { name: 'my-app' }, [reactNativeAdapterBlueprint])

Then write your domain as you would anywhere else:

import { Controller, Match } from '@stone-js/router'

@Controller()
export class TaskController {
  @Match('/tasks/:id')
  show (event) {
    return this.tasks.find(event.get('id'))
  }
}

Configuration

Every key is optional.

| Key | Description | |---|---| | stone.reactNative.baseUrl | The base an in-app path resolves against. Defaults to stone://app. Set it to your own scheme so links and in-app navigation share an origin. | | stone.reactNative.navigationSource | The navigation source. One is created during the build phase and shared with the router; supply your own to control the linking module. | | stone.reactNative.cookie.options | Options for the in-memory cookie collection. |

Learn More

• Documentation
• Continuum Architecture

API documentation

See the published API reference.

Contributing

See CONTRIBUTING.

License

MIT