ctc-mobile-design-system

CTC Design System

CTC design-system components library for housing reusable components and theme; to be used across ctc's mobile-app suite.

NOTE: This documentation only covers the architectural aspect of the library. It does not go into detail about the tools and technologies getting used in it. The responsibility of understanding those are left up to the developer.

This library has two different entry points based on what context you're using it. There are two contexts:

• development in the library
• using a published version in one of our apps

We will be discussing each of these contexts separately.

Development

We are providing two utilities in this library:

1. Reusable Components
2. Themes object

While creating reusable components in this library, we are expected to work on the following features:

1. Documentation (storybook)
2. Unit testing (jest/react-testing-library)
3. Coding in Typescript

Package Manager

We use yarn as default package manager in this library.

Storybook

You will find the storybook content in the storybook folder at the root of the project. Here we will write our stories and add any addons we find necessary. You can find the list of addons available in React-Native here. And also, currently, we are using a ThemeProvider addon which we will discuss in the Theme section.

For each component we develop, we will add its story file in storybook/stories/component-name.stories.tsx. To run storybook we will run the following commands:

1. yarn storybook
2. yarn android/yarn ios

The second command will look up our index.ts file in the root of the project which will render the storybook view in the emulator. This is the entry point getting used in the development context. Here you will be able to view your stories and interact with them as you wish.

Testing

Test cases for each component will be written in the src/__tests__ folder. To run jest locally, use the command yarn test. Please note that we are automatically running tests on each commit using Gitlab's CI pipeline, so once you're finished with your task, make sure all your tests are passing before you create the PR. Also, in case you update the UI of an existing component, be sure to push its updated snapshot file as well otherwise your test will fail for that component. Learn more about it here.

Typescript

We are required to write code in Typescript but the apps using this library only support Javascript. Therefore, we have to make sure that the code we publish in the final package is converted to Javascript first. The CD pipeline is handling this process for us but if we want to use the local version of the library in the apps (for testing purposes), we need to do it manually. There are two main points to it:

• Define what part of our codebase we want to publish. Testing and documentation are only required for development so we don't want their code to be included in the final package. To specify what code we want to include, we make use of the files field in package.json.
• Convert your Typescript code to Javascript using the yarn compile command. To specify which code to convert and where to store the output, we are making use of tsconfig.json. Here we are telling it to only convert the code in the src (which contains our components and themes object) and store it in the dist. And in the files field in package.json we are passing in the path to the dist.

Themes

We will discuss the typography in our themes object. typography contains two subsections font-family and font-size.

To specify the font-size, we're using the react-native-responsive-screen. And since this library is getting used in our components which will be getting used in our apps, we have added it in dependencies in package.json. Please read up on dependencies, devDependencies, and peerDependencies. Understanding their purpose and difference is critical when creating libraries.

We are using custom fonts. You can find the list of these fonts in src/assets/fonts. Read up on the process of enabling custom fonts in React-Native here. We need to enable them separately in our library (to be able to use them in Storybook) and in our apps. This has already been done in both the library and the applications (as of now it is only done in the consumer app) but you are required to understand the process nevertheless.

Using our theme(s)

We are making use of the Context API to use our theme and styled-components for styling in general.

To use our theme in the applications, we need to wrap the root component in ThemeProvider provided by styled-components and pass in the theme object. Then we can apply the style to the components dynamically via props. An example can be found here.

To use our theme in storybook, we are using an addon that mimics the behavior of a ThemeProvider. Learn more about its setup and implementation details here.

CI/CD pipeline

Our CI/CD pipeline consists of three stages:

1. Install
2. Verify
3. Release

Install

Simply installs the packages.

Verify

Verifies that there are no linting errors in the code and the unit tests are passing.

Release

Note that this stage is only executed when you're publishing your changes.

In order to make sure your changes get published, follow the following steps:

1. Once you're done with your task, squash your commits in your branch into a single commit.
2. Ensure that that commit message is following the convention mentioned in this link.
3. Ensure that your MR contains only one commit, whose message is following the convention mentioned in the previous step.
4. Once your MR is approved and merged, your changes will automatically get published.

This stage only runs on the main branch. It converts Typescript to Javascript then it bundles it up and creates a package out of it using semantic-release.

1. Convention we need to follow: details
2. Semantic versioning: details

Installation

After you install the package it'll give you a dist folder with an entry point of dist/index.js.

As NPM Package (Preferred)

This library can be installed in the project as NPM package. Refer to @development-team20/novin package page for more details on latest version.

In general, there are the following steps to install the package:

1. Go to your application repo and run:
2. npm config set @development-team20:registry=https://gitlab.com/api/v4/packages/npm/
3. npm config set'//gitlab.com/api/v4/packages/npm/:_authToken=${GL_NPM_TOKEN}
4. Your .npmrc file should look like this:

@development-team20:registry=https://gitlab.com/api/v4/packages/npm/
//gitlab.com/api/v4/packages/npm/:_authToken=${GL_NPM_TOKEN}

NOTE: This file is telling npm which registry to look for when downloading a package whose name starts with @development-team20. Our packages are private by default and they're not hosted on the public registry. You can view the list of all the packages available in our registry here. 3. Install the package via npm install @development-team20/novin. 3. yarn is not working right now, so we will use npm for now.

As GitLab Module

1. In the package.json of your project's dependencies, add the following line: "@development-team/novin": "git+ssh:/[e-mail]:development-team20//design-systems/ctc-novin.git#main"
2. Install the package via npm i
3. Done

Test package locally before publishing it

While we are adding new components/features to this library we will need to test them in our apps to make sure they're working as expected. We can't keep publishing our changes to the registry while we're in development mode because that'll pollute the versioning and commit history and create packages we won't be using in the end. To solve this issue, we will be installing local versions of our published packages through the following steps:

1. Make the changes you need and then run yarn compile to convert your typescript to javascript. This command will create a dist folder which you will publish.
2. Run the command npm pack. This command will create a .tgz file which would contain the exact content if you were going to publish the package to npm. It will give you a file looking like development-team20.novin-0.0.0.tgz
3. Go to your target directory and run yarn add file:../path-to-tgz.
4. You can now use the package as expected.

NOTE: You will need to run these steps again every time you make a change. Or if it's possible, you can go to the node_modules, find this package and update the files there directly. In this case, just make sure you copy over your changes to the library repository before you're ready to push your changes.

NOTE: You can read up more on how to test an npm package locally. This article discusses multiple options but keep in mind that the npm link command does not work with React-Native because it does not support symlinks. Read more about it here.

Troubleshooting

In case of reuseable views not rendering on build use the following way on windows machine

// in package.json replace
"storybook": "start-storybook -p 7007" // with
"storybook": "start-storybook -p 7007 -h <ip_of_your_system>" // replace this with your local ip address

// in storybook/index replace
const StorybookUIRoot = getStorybookUI({}) // with

const StorybookUIRoot = getStorybookUI({
  host: <ip_of_your_system>, // replace this with your local ip address
  port: '7007',
});