Getting Started

A Candescent D3 mobile application is built using React Native, a popular Javascript framework that combines the best parts of native development with React, a best-in-class JavaScript library for building user interfaces. With tailoring and extensibility at its heart, customers can easily modify standard product to better match their brand identity or to provide their customers with a connected and customized experience.

The core of the application is the Candescent D3 React Native Framework, a high-level, opinionated framework built on top of React Native building primitives and proven open-source React and React Native libraries.

To achieve the goals of tailoring and extensibility, a Candescent D3 mobile application is organized as a monorepo - a single repository containing multiple distinct projects, with well-defined relationships, along with the tooling for them. The tenant of this monorepo is Nx, a smart, fast and extensible build system with first class monorepo support and powerful integrations.

While React Native is a Javascript framework, a Candescent D3 mobile application is entirely written in Typescript, a superset of JavaScript that provides type safety and a better developer experience.

Prerequisites

Throughout these docs you will need to have an understanding of React and React Native fundamentals. You should also be familiar with Typescript and have some prior experience using Javascript package managers like npm and yarn.

If you are new to any of these prerequisites or you need a refresher, here are some resources to help you out:

1. Main Concepts of React
2. React Hooks
3. Getting Started with React Native
4. Typescript Handbook
5. Getting Started with Yarn

Accessing private packages

All Candescent D3 packages used by the Candescent D3 mobile application are private npm packages. You will need an access token to be able to access them and you will also need to add this to your environment variables on your development machine.

Add the following lines to your ~/.bash_profile or ~/.bashrc (if you are using zsh then ~/.zprofile or ~/.zshrc) config file:

export NEXUS_USER="nexus_username"
export NEXUS_PASSWORD="nexus_password"

and then refresh your environment variables by sourcing the file that you edited. For example:

source ~/.bash_profile

warning

.bash_profile is specific to bash. If you're using another shell, you will need to edit the appropriate shell-specific config file.

Verify that NEXUS_USER and NEXUS_PASSWORD have been set by running:

echo $NEXUS_USER $NEXUS_PASSWORD

Setting up the development environment

Before being able to run a Candescent D3 mobile application you have to correctly setup the development environment. Please note that a Mac is required to build projects with native code for iOS.

To setup the development environment, you can follow the instructions from the official React Native docs, following the path for React Native CLI Quickstart and macOS as a development OS. Make sure you setup both iOS and Android as Target OS, since the setup is different for each of them.

For iOS you will need to install ruby and cocoapods, we recommend using a ruby environment manager (we use rbenv), after you init rbenv and downloaded and set a ruby version either global or local for project folder, you'll also need to install an additional dependency

gem install xcodeproj

info

You can skip the instructions for setting up a new React Native project and running it, but it might be helpful to follow them anyway to confirm that the development environment has been setup correctly.

Minimum requirements

On top of those instructions, please make sure the dependencies you setup have these minimum requirements:

• Node.js version 16.14 or above (which can be checked by running node -v). You can use nvm for managing multiple Node versions on a single machine installed.
• XCode version 13.3 or higher

Installing Yarn

You will also have to install yarn, since it is used as the Javascript package manager for managing application dependencies instead of npm. We generally prefer installing all needed tools using Homebrew, but there are other alternatives available, as documented on the installation guide.

Getting the application

Typically, each Candescent D3 mobile application have their own Git repository that you can clone locally:

git clone git@github.com:LodoSoftware/myorg.git

Once you cd to the newly created directory, install all project dependencies using yarn:

yarn install

tip

If you get any 404 Not Found errors while getting packages from the package registry, make sure you setup the NEXUS_USER and NEXUS_PASSWORD environment variable correctly at the previous step.

It is also possible to start from scratch by bootstrapping an entirely new application with some defaults. Read more about this option in the advanced guide.

Running the application

With the development environment ready and all the project dependencies installed, it is now time to run the Candescent D3 application.

Running on iOS

Use the following command to run the application on the iOS simulator:

yarn ios

Running on Android

Use the following command to run the application on the Android emulator you created during setting up the development environment:

yarn android

Both these commands are just npm script aliases for Nx tasks. To understand what they do, it is now time to discuss about the application structure and the tooling that Nx provides when working with different projects living inside a Candescent D3 monorepo managed by Nx.