React Onboarding

Objectives

In this artilcle, you will:

• Download and install all the necesarry tools to get started developing on our React projects
• Clone the needed projects and learn how to set them up
• Get started on the issue your project manager provided you in the email linking you to this document

Prerequisites

To get started, you will need:

• Your FullCount formatted laptop
• To get logged in to everything productivity-wise you need (Outlook, Microsoft Teams, 365 Slack, KeePass, etc)
• Have completed all your HR onboading trainings & orientation meetings
• Have gained access to Dev BackOffice and picked out an unclaimed community to take over and use for testing
• Communities whose names are just numbers are free to take over! If it's got a name, though, some other developer has already claimed that one
• Have gained access to the FullCount Github
• You should've recieved an invite to this in your email. Create an account with your Fullcount email

Sweet, let's get going!

Instructions

Necessary Software

Some of this may already be installed for you - make sure you've got it all!

• VSCode (or, your favorite IDE)
• Git (for repository management)
• Github Desktop (for easy visual representations of repository management)
• Node.js (Primary environment)
• React DevTools (For debugging in your browser)

Recommended VSCode setup

In order for VSCode to dynamically lint our react-utility typescript project with our linter settings, you will need to add the following code to your settings file. Without these lines, linting will only be executed on project build.

• Use Ctrl + Shift + P to search a command.
• Search 'user settings' and choose 'Preferences: Open User Settings (JSON)'
• Copy this code, paste, and save the file:

"eslint.validate": [

"javascript", "javascriptreact", "html", "typescript", "typescriptreact",

],

"typescript.validate.enable": true,

Other than that, we've got a few recomended extensions and settings!

1. We reccomend turning on Autosave
• To do this, press Ctrl + Shift + P like you did above and type in "Autosave"
• You should see an option that says "File: Toggle Auto Save". Press enter to turn this on, and your files should automatically save as you edit them
2. We recommend installing the extensions ESLint, Prettier, and ES7+ React/Redux/React-Native snippets
• You can do this in the Extensions tab on the left! The icon looks like this: 
3. If you're a Bash enjoyer, we reccomend configuring Git Bash as your terminal in VSCode!
• If you're going to do this, make sure you installed Git Bash when you installed Git!
• In VSCode, press Ctrl + ` to open the terminal
• Then, press Ctrl + Shift + P to open the command pallate
• Search for "Select Default Profile"
• Select Git Bash from the options
• Save your settings, then close and reopen VSCode (or, just open a new terminal). It should now be in Git Bash!

Helpful VSCode Shortcuts

Here are a few helpful VSCode shortcuts for you to enjoy!

• Ctrl + Shift + F - Find in project
• Ctrl + P - Search files
• Ctrl + t - Search Functions and Variables
• Ctrl + Shift + P - Open Command Pallate
• Alt + Up Arrow or Down Arrow - Move selection up / down, respectively
• Alt + Shift + Up Arrow or Down Arrow - Duplicate line selection up/down, respectively

Setting up your Development Environment

Cloning needed repos

Now, you'll need to clone down all the repos you'll need for the project you will be working on! Depending on which project you're working on, it will have different sub-repositories it requires. At some point we will consolidate this so it's consistent. Currently:

• Batch Order Entry requires react-api and react-components
• Retail PoS requires react-api, react-components, and react-payments
• Engage (Customer Portal) requires react-utilities
• Self Service requires react-utilities, react-api, react-components, and react-payments

An exhaustive list of our repositories in Github is available here. Also, you can check this page to see a more organized list

Clone all the repos you will need to work on whatever project you will be working on! Clone them all in the same directory. I reccomend C:/Code

NOTE: These above requirements may change as dependencies get updated and / or removed. So, how do you tell which ones you'll need? I'm glad you asked!

Look at the package.json file in the base directory of the project you're going to develop in. In there, look for lines that look like this:

Here, you can see these two grab from github:FullCount-Development, while the other dependencies merely have a version number:

If they point to a github:FullCount-Development like the first example, that means it's an internal repository that's being referenced. Github is confiugred to automatically provide a production build to our local npm, so it will work just fine without you cloning those repos. However, you may run into an instance where you need to make changes to these dependencies, in which case you will need them cloned! We will go through getting the main project to use your locally cloned versions next in this tutorial

Linking & Unlinking development repositories

One thing you'll have to is use the npm link command to allow yourself to work on our local dependencies and then test them in your parent project! This is actually pretty easy

I'm working on Batch Order Entry, which depends on react-api and react-components. I'll start with react-api!

First, navigate to the directory of the dependency you want to do development for

Sweet! Now run npm link:

Perfect! Now, make sure you have the local version built so your application can properly use it as a dependency. To do this, run npm run build

if you haven't already, make sure to run npm ci before building so your dependency has everything it needs to compile!

NOTE: When making changes to a dependency, you will need to regularly run the npm run build command, rebuilding the dependency with your new changes. If you don't, your main project will be still using the old version as, while npm link is awesome, it cannot use uncompiled versions of your code!

While you'll have to run npm run build every time you make changes, you only have to run npm link the first time you clone the dependency! Pretty cool

Repeat these steps for all of the dependencies required for your project! Even if you're not going to make any edits to them yet, we reccomend doing this with all of them right away just to get things initially configured!

Next, you're going to need to tell your main repository to look at your local versions instead of the ones you've pulled from npm!

First, on your main project, make sure you've ran npm ci to do a clean install of exactly what's in package-lock.json! 

Next, you'll need to tell npm to use the local version of the dependencies you're trying to edit. In my case, since I'm editing react-api, I will simply run npm link @react/api to indicate that the @react/api dependency should be grabbed from the local machine!

NOTE: You should only have your main project using your local dependencies if you're making changes to them! Otherwise, it's going to be easier to use the remote versions - that way changes made by other developers will be automatically added to your codebase with an npm update

and then, do this for the other dependencies you want to edit - in my case, npm link @react/components

Make sure to be running npm run build to ensure the changes you make actually get tested on your main project! You may have to reload your page to make sure they're coming in as well

Once you're done making changes to the dependency, make sure you're pushing your changes to a separate branch, creating a Pull Request, and submitting it for review alongside any changes you had to make in your main project - add links to both of these in Redmine! Then, make sure to unlink the local repos from your project! To do so, simply run npm unlink --no-save @[dependency] - in my case, npm unlink --no-save @react.api

note the --no-save - very important! Also, note the difference of / vs . in the indication of which dependency to change

NOTE: We've got some nifty little helpers in package.json to help you with this process! On most of your projects, simply running npm run link-react will link to all the dependencies required, and npm run unlink-react will switch back to using the remote versions. Just remember that these helpers do ALL of the internal dependencies on your project, so you'll need to have to have them all cloned, npm linked, and up to date!

Setting VSCode up with a workspace

One nifty thing you can do in VSCode is set it up as a workspace, allowing you to have all the necessary dependencies open alongside your main project! To do so, first open your main project folder

or, File > Open Folder if you've already got something open

Then, press File > Add Folder to Workspace!

This will bring up the file explorer, where you can navigate to the parent directory and select the folders of your dependencies. For example:

Then, do this for all other dependencies! Here's what mine looks like for Batch Order Entry:

Then, you'll want to got to File > Save Workspace As to save this workspace and be able to use it in the future! I recccomend saving it in your C:/Code or equivelant directory (the parent directory for where all your repos are stored)

Getting Started

Great! You're ready to get running. First, run npm run dev to run a local development version of the react project you will be working on - this should be on the main project!

Then, take a look at your Redmine task referenced earlier. If you don't have one yet, ask your project manager! 

On your issue, you'll see some details. Check out a new branch for this issue, starting with the issue key. This is the issue key:

And then include a descriptive name. For example, my branch for the above issue was called 17738-wrong-dietary-tag-description-used

To get a deeper understanding of how we use Redmine, check out this article on the Redmine Development Task Workflow

Important Reading

Here are some essential documents to read through to get yourself situated in development here at FullCount!

• If you didn't check it out in the previous step, you should read the Redmine Development Task Workflow
• Committing Code Guidelines
• Development Best Practices
• Developer Emails and Email Rule Reccomendations
• Read through the Java Developer Guide - it contains a lot of helpful information about our processes not documented here, although you can skim most of it

Further Learning

Looking to deepen your knowledge in the technologies we use? Here are a few great resources we reccomend checking out!

• PluralSight - React 18 Courses (Learn React)
• YouTube - React Tutorial for Beginners (Concise introduction to React concepts)
• Our Git Guide (to give you an easy crash-course on using Git)
• For Java development work, check out our Java Developer Guide and follow the installation guide linked in there
• Look through this document, there are some useful resources linked in it as well