rm-mobile-design

A React Native component library and design system

Development workflow

Create a .env file in the root of the project, containing a the Zeplin personal access token:

# .env

ZEPLIN_PERSONAL_ACCESS_TOKEN={ZEPLIN_PERSONAL_ACCESS_TOKEN}
```sh

Run `yarn` in the root directory to install the required dependencies for each package, and generate the theme files.

> **_NOTE:_** While it's possible to use [`npm`](https://github.com/npm/cli), the tooling is built around [`yarn`](https://classic.yarnpkg.com/), so you'll have an easier time if you use `yarn` for development.

While developing, you can run the [storybook app](/example/) to test your changes. Any changes made to the component library code will be reflected in storybook without a rebuild. If you change any native code, then you'll need to rebuild.

To start the packager:

```sh
yarn example start

To run the storybook on Android:

yarn example android

To run the storybook on iOS:

yarn example ios

To run the storybook on Web:

yarn example web

To watch for changes to stories you can use:

yarn example storybook-watcher

Make sure your code passes TypeScript and ESLint. Run the following to verify:

yarn typecheck
yarn lint

To fix formatting errors, run the following:

yarn lint --fix

Commit message convention

• fix: bug fixes, e.g. fix crash due to deprecated method.
• feat: new features, e.g. add new method to the module.
• refactor: code refactor, e.g. migrate from class components to hooks.
• docs: changes into documentation, e.g. add usage example for the module..
• test: adding or updating tests, e.g. add integration tests using detox.
• chore: tooling changes, e.g. change CI config.

Linting and tests

ESLint, Prettier, TypeScript

We use TypeScript for type checking, ESLint with Prettier for linting and formatting the code, and Jest for testing.

Our pre-commit hooks verify that the linter, tsc, and tests pass when committing.

Scripts

The package.json file contains various scripts for common tasks:

• yarn bootstrap: setup project by installing all dependencies and pods.
• yarn typecheck: type-check files with TypeScript.
• yarn lint: lint files with ESLint.
• yarn test: run unit tests with Jest.
• yarn example start: start the Metro server for the example app.
• yarn example android: run the example app on Android.
• yarn example ios: run the example app on iOS.

Pre-release testing via expo

Most changes to components in this library can be tested in isolation using the storybook app, rather than in a project that consumes this library.

In order for the storybook app to be accessible on a real device using expo go, it needs publishing to expo.

1. Authenticate through the expo CLI using the shared account
2. yarn example publish-test will create a branch in expo with the same name as the currently checked out branch.
3. You should now be able to login to expo go on a real ios or android device and access the published branch.

Releasing

There are various steps required to publish a new version of this library.

### Release branch

Before publishing a new version, we must create a release branch.

Please ensure that:

• The source is correct. Usually, for a new major/minor release, this will be develop, however occasionally we may want to patch existing versions, in which case the release branch should be created off the tag for the version being patched.
• The version number is correct. Please consider all changes that may have gone into the develop/source branch, not just your most recent changes.

For example, creating a new major release branch from develop: git checkout develop git checkout -b release/2.0.0

Or, creating a patch release branch from a previous major release: git checkout -b release/1.1.2 v1.1.1

Publishing to npm

Once a release branch has been created, we must publish the new version to NPM.

1. Checkout the release branch
2. Update the version number accordingly in package.json, and commit the change
3. Run yarn publish
4. Press enter to automatically select the version from package.json (This should be the one that was updated in step 2)

Creating a GitHub release tag

Once the package is published to NPM, create a new tag and release in GitHub, from the release branch, named so:

Tag: v<x.y.z>

Release name: Release <x.y.z>

Backfilling patch changes

If a previous version has been patched, please ensure that any changes are backfilled into develop.

Publishing to expo

The production branch in expo contains the most recent released version of the library.

Updating this is required when publishing a new version to NPM, as the production expo branch needs to be updated to reflect the most recent release.

1. Authenticate through the expo CLI using the shared account
2. Checkout develop
3. In project root, run yarn example publish-prod
4. You should now be able to login to expo go on a real ios or android device and access the production branch.

Installation

Install peer dependencies

react-native-safe-area-context

yarn add react-native-safe-area-context

react-native-picker

yarn add @react-native-picker/[email protected]

react-native-vector-icons

yarn add react-native-vector-icons

lottie-react-native

yarn add [email protected]

lottie-ios

yarn add [email protected]

@react-native-community/datetimepicker

yarn add @react-native-community/datetimepicker

This component library requires manual installation of the following icon fonts:

• FontAwesome
• AntDesign

Follow react-native-vector-icons' installation guide to add these.

Theme fonts

You will also need to add Fonts for the default theme, as well as any Fonts used by any custom themes.

Default fonts:

• Open Sans Regular
• Open Sans Medium
• Open Sans Semi Bold

You can easily add fonts for both iOS and Android by using react-native-asset.

Install this package

yarn add @rotamaster/rm-mobile-design

Additional step for IOS:

cd ios
pod install

Usage

Theming

Themes are based on the MD3 design system (https://m3.material.io/m3/pages/color-system/color-roles).

See the default theme for an example.

Using a custom theme across the whole application

You can either pass through a complete custom theme, or import the default theme and extend it using the spread operator.

If no theme is provided, the default theme will be used.

NOTE: Please ensure any provided fonts are set up for use in the project.

// ...
import {
  Provider as RmDesignProvider,
  Theme,
  TextInput,
  defaultTheme,
  ThemeTypography,
} from '@rotamaster/rm-mobile-design';

const App = () => {
  const typography: ThemeTypography = {
    ...defaultTheme.typography,
    labelLarge: {
      fontFamily: Platform.select({
        web: 'Times New Roman',
        ios: 'System',
        default: 'sasns-serif',
      }),
      fontWeight: '400',
      letterSpacing: 0.5,
      lineHeight: 22,
    },
  };

  const customTheme: Theme = {
    colors: {
      ...defaultTheme.colors,
      primary: 'red',
    },
    typography,
  };

  return (
    <RmDesignProvider theme={customTheme}>
      <View>
        <TextInput /> // Component will be styled using provided theme
      </View>
    </RmDesignProvider>
  );
};

Accessing the theme

// ...
import { useTheme } from '@rotamaster/rm-mobile-design';

const MyComponent = () => {
  const theme = useTheme();

  return (
    <View style={{ backgroundColor: theme.colors.background }}>
      <Text style={{ color: theme.colors.text }}>
        Hello, World
      </Text>
    </View>
  );
};