scene-router: A JavaScript repository from Pressly Inc.

scene-Router (v2)

A complete scene routing library written in pure JavaScript for React Native. It supports iOS and Android. The api is so easy that you just have to learn only 2 simple things, scene decorator and Router component.

Description

We, at Pressly, using react-native and our app consists of large number of scenes. We wanted somthing super simple, it went through a lot of internal reversion, until we decided to open source it.

scene-router supports the following out of box:

url like path, which can contains params and query strings. e.g. '/user/:id'
passing custom props to target scene
storeless, you can connect to redux or mobx stores
reset stack of scenes
animating scene from all 4 direction
gesture enable
configure scene settings at scene difinition and route time
all animation are being configure to optimize useNativeDriver feature

Installation

npm install scene-router

Prerequisite

we recommended to use decorator. It makes the code a lot easier to maintain. If you don't want to use it, that's ok too.

in order to enable decorator in your react-native project follow the 3 steps below,

1: install babel-plugin-transform-decorators-legacy using yarn or npm and 2: configure your .babelrc file as follows

{
  "extends": "react-native/packager/react-packager/rn-babelrc.json",
  "plugins": ["transform-decorators-legacy"]
}

3: if you are using flowtype, make sure to add esproposal.decorators=ignore under [options] tags inside .flowconfig file

Usage

There are 2 things you should learn about scene-router in oreder to start using it in your project

`scene` decorator

scene is a decorator feature which register your component as a scene. here's an example

import React, { Component } from 'react'
import { scene } from 'scene-router'

@scene({
  path: '/scene1'
})
class MyFirstScene extends Component {
  render() {
    ...
  }
}

a little bit of explaination, what we did was adding scene as a decorator on top of our first component MyFirstScene. We were passing path. This is our path to this scene. so every time, Router wants to render this scene, all it needs a path url. scene-router will handle all coordinations and animations behind the scene.

you might ask, so what if I want to show my scene from top to bottom. As I said, scene decorator accepts many arguments. except path the rest of the arguments are optional. here's the list of all options

option	type	required	default value	route time change	Description
path	String	Yes	N/A	No	register a scene with this unique path
side	Side	No	Side.FromRight	Yes	how the scene will animated, from which side
threshold	Number	No	30	Yes	how far from side you have to swip to make the gesture working
gesture	Boolean	No	true	Yes	enable or disable gesture
reset	Boolean	No	false	Yes	all scenes prior to this scene will be destroyed
backgroundColor	String	No	white	Yes	the back color of each scene

ther are 5 differant sides you can choose from

name	description
FromLeft	Animate the Scene From Left to Right
FromRight	Animate the Scene From Right to Left
FromTop	Animate the Scene From Top to Bottom
FromBottom	Animate the Scene From Bottom to Top
Static	No animation

There is one little thing, every component which decorated with scene will have a method called, updateSceneStatus(status: Status). This method will be called based on whether your scene is Active, InActive, MightActive or MightInActive. In other words, We are adding 4 more lifecycles to React. remember this is just a utility to help you!

import React, { Component } from 'react'
import { scene, Status } from 'scene-router'

@scene({
  path: '/scene1'
})
class MyFirstScene extends Component {
  updateSceneStatus(status) {
    switch(status) {
      case Status.Active:
        break
      case Status.InActive:
        break
      case Status.MightActive:
        break
      case Status.MightInActive:
        break
    }
  }

  render() {
    ...
  }
}

here's a little bit of description:

value	Description
Active	when the animation is done and scene is visible
InActive	when a scene is already covered or gone
MightInActive	during dragging a scene. the current scene will get this value
MightActive	the previous and covered scene by current during dragging with get this value

`Router` component

the second thing to learn is Router. This is your entry point of your app. It has only 3 props, area, action and config.

area is a string which defines an area with a name. if you plan to use tabs, each individual tab must have a unique name, that name can be passed to area
action is a string which accepts either goto or goback. if you pass goback, the 3rd prop, config, will be ignored.
config is defining which path you want to go and if you want to override any scene configuration.

here's an example of Router

import React, { Component } from 'react'
import { View, Text } from 'react-native'
import { scene, Router } from 'scene-router'

@scene({
  path: '/scenes/:id'
})
class Scenes extends Component {
  render() {
    const { route: { params } } = this.props

    return (
      <View style={{ flex: 1}}>
        <Text>{params.id}</Text>
      </View>
    )
  }
}

class App extends Component {
  constructor(props: any, context: any) {
    super(props, context)

    this.state = {
      area: "default",
      action: 'goto',
      config: {
        path: '/scenes/1'
      }
    }
  }

  render() {
    const { area, action, config } = this.state

    return (
      <Router
        area={area}
        action={action}
        config={config} />
    )
  }
}

NOTE Router component also accepts one Componet as a child, This Component is being displayed and renderd first before the first route is triggered. this is a good place to put your splash screen.

Cheers.

pressly/scene-router