react-native-tvos/rnn-starter-tv

🤹 Production-ready starter for your next React Native App! Powered by cli-rn, React Native Navigation, RN UI lib, Mobx, Reanimated 2, Notifications, Permissions, Dark Mode, Localization, and much more.

rnn-starter.mp4

This starter is a collection of libraries and approaches from my personal experience. No hard judgements ✌️

For more information, check out Why section.

This branch includes support for Android TV and Apple TV.

• Framework changes:
  • Use react-native-tvos 0.64.2-4 instead of react-native 0.64.2
  • Patches for podspecs and Objective-C source in several projects
• App changes:
  • tvOS targets in Xcode project
  • Add tvOS support in Podfile
  • Orientation should be both portrait and landscape (needed for Android TV)
  • Make Bounceable component work on TV
  • Scrollview inset adjustment should not be "always" on TV
  • For now, use async storage instead of MMKV
  • TV remote event display on main screen for Apple TV
  • Local option for simulating counter API calls

rnn-starter-appletv.mp4

Getting Started

Quick start with cli-rn

> npm i -g cli-rn
> cli-rn new AppName

If you encounter any problems with cli-rn, please open an issue.

If you have any troubles running the app with yarn ios or yarn android, open XCode or Android Studio and run the project from there.

Manual setup

1. Clone the repo

> git clone https://github.com/kanzitelli/rnn-starter.git AppName && cd AppName

2. Remove .git file (if not planning to contribute)

> rm -rf .git

3. Install packages and pods

> yarn && yarn ios:pods

4. Run it!

Open XCode or Android Studio to run the project (recommended) or do

> yarn ios
> yarn android

For Android TV, start an Android TV simulator from Android Studio, then execute yarn android just as you would for Android phone.

For Apple TV, execute yarn tvos.

If you need to rename the app, do the following (based on react-native-rename):

> yarn rename NewAppName
> yarn ios:pods

What's inside

• React Native Navigation - truly native navigation experience for iOS and Android.
• RN UI lib - amazing Design System, UI toolset & components library for React Native. Dark Mode is implemented using this library.
• Reanimated 2 - React Native's Animated library reimplemented.
• MobX - simple, scalable state management, with mobx-persist-store for persisting your stores.
• AsyncStorage MMKV - efficient, small mobile key-value storage framework developed by WeChat. ~30x faster than AsyncStorage!

Extra helpful libraries

• React Native Navigation Hooks - a set of hooks for React Native Navigation.
• React Native Vector Icons - customizable icons for React Native.
• React Native Gesture Handler - native touches and gesture system for React Native.
• React Native Device Info - device information for React Native iOS and Android.
• Hermes Engine - a JavaScript engine optimized for running React Native apps.
• ESLint + Prettier - keep your code neat and structured.
• Patch Package - useful for fixing node modules instantly.
• Release It - automate versioning and publishing of your app.
• Typescript - strict syntactical superset of JavaScript.

Useful services/methods

• navigation - a service where all navigation configuration takes place in. It simplifies and abstracts the process of registering screens, layouts, etc.
• translate - a service that brings easy integration of localization for an app by using i18n-js and react-native-localize. You can see an example of en and ru localizations in Example screen.
• onStart - a service where you can write your own logic when app is launched. For example, you can increment number of appLaunches there.
• configureDesignSystem() - a method where all settings for an app's design system is taking place. You can customize there colors, schemes, typegraphy, spacings, etc. Now you can add as much theme modes as you want.

Advantages

Describe app screens in one place

All setup for your screens takes place in one file src/screens/index.ts:

type Screen = 'Main' | 'Settings' | '...';

const screens: Screens = [
  {name: 'Main', component: Main},
  // ...
];

const screensLayouts: ScreensLayouts = {
  Main: {
    name: 'Main',
    options: {
      topBar: {
        ...withTitle('Main'),
        ...withRightButtons('inc', 'dec'),
      },
      ...withBottomTab('Main', 'newspaper'),
    },
  },
  // ...
}

Navigate to other screens with predictability

const Screen = ({componentId}) => {
  const {nav} = useServices();

  return (
    <View>
      <Button
        label="Open Settings"
        onPress={() => nav.push(componentId, 'Settings')}
      />
    </View>
  )
}

Build layouts with ease

One screen app:

Navigation.setRoot(Root(Stack(Component(screensLayouts.Main))));

Three tabs app:

Navigation.setRoot(
  Root(
    BottomTabs([
      Stack(Component(screensLayouts.Main)),
      Stack(Component(screensLayouts.Example)),
      Stack(Component(screensLayouts.Settings)),
    ]),
  ),
);

Simplified API for Shared Transitions

nav.push<ExampleScreenProps>(
  componentId,
  'Example',
  { value: randomNum() },
  withSharedTransitions([{ id: 'reanimated2', pop: true }]),
)

As much theme modes as you want

You can define theme modes in utils/designSystem.tsx and toggle them from any part of the app.

Samples for new screens, services, stores and components.

So you have one structure within the project. You can find them in corresponding folders. Just copy&paste it and make the necessary changes.

Enhancements

There are still some things I would like to add to the starter:

General

• Shared transitions example
• Passing props to a screen example
• Constants: add Dimensions, Navigation (nav service)
• AsyncStorage stores persisting example
• API example + useEffect and start logic on a screen
• Example with theme modes change
• Move some services/scripts to separate libraries, e.g., rnn-layouts
• Better documentation/exlanation for project structure, stores, services, etc.

Production

• Auth flow
• Fast Image - DylanVann/react-native-fast-image
• Notifications — wix/react-native-notifications
• E2E tests - wix/Detox
• Permissions — zoontek/react-native-permissions
• FB SDK — thebergamo/react-native-fbsdk-next
• Appodeal — appodeal/react-native-appodeal
• In-app purchases — dooboolab/react-native-iap?

Feel free to open an issue for suggestions.

Known issues (warnings)

• Large title is not shown on 2nd+ tab. This issue exists and there is a patch for fixing it. You can find it in patches/react-native+0.64.2.patch. It will be autorun when you do yarn add/remove/etc.
• Over-The-Air Updates. They have been removed from the current version as I had some problems publishing one of the apps to AppStore. Check out my tweet and be aware of the issue if you'd like to use them anyways.
• Dark Mode on Android. Android doesn't toggle top and tab bars' background color to dark when dark mode is toggled on. However it happens so on iOS. As a workaround, we can subscribe to toggle events and then using Navigation.mergeOptions & Navigation.setDefaultOptions to change stylings for navigations and tab bars. Anyways, it needs some time to dive into it and come up with better solution from native side.

Worth checking

Articles

• Expo + React Native Navigation? Yes! - Medium, Dev.to
• cli-rn — making RN app developing experience as smooth as possible - Medium, Dev.to

Apps in production

• Wallpapers App - App Store, Twitter
• Rabbit App. Lite Reddit client - Github, App Store, Google Play
• Trip Music Radio - App Store, Google Play
• App for VK - App Store
• Messenger for VK - App Store
• Christmas Market - App Store

Why

...do we need yet another starter/boilerplate? Well, I work with React Native for more than 3 years and during the time I started having my own project structure which was a good fit for almost all of the delivered apps. Also, I have come up with some custom useful services/methods which simplify usage of React Native Navigation and other libraries. Check out Advantages section.

License

This project is MIT licensed