my-smart-payroll-calculator

SmartPayroll - Sign up and Calculator

This app is SmartPayroll Sign up process.

It's comprised of a React app for the frontend based on Alphero's React Boilerplate and an Express server that provides a simple API.

Pre-requisites

• Node 12.

Nice to have

• Netlify CLI, in case a manual deployment is needed.
• Heroku CLI, same as above (migrating to use CRM built by Datacom - will update this once work is complete)
• SmartPayroll CRM API documentation built by Datacom - https://smartpayroll-devphase2.azurewebsites.net/Help

Development environment

To get started working on the project, from the terminal run the following commands:

• yarn install:all (installs both client and server).
• yarn start:dev

Environment variables

During runtime

These are the environment variables used in the app at runtime:

• REACT_APP_ENVIRONMENT: Just set to dev.
• REACT_APP_API_URL: Set to where the Node server is available in development.
• REACT_APP_GTM_CODE: Id for Google's Tag Manager. The account is managed by Smart Payroll itself.
• REACT_APP_GOOGLE_PLACES_API_KEY: API Key for Google Places.
• REACT_APP_GOOGLE_API_URL: URL for querying the Google Map API
• REACT_APP_CRM_API_URL: URL for the CRM API. There are certain queries that are done against the API we build and others that come from the CRM. Both URL's are needed in the deployment files.
• REACT_APP_TOKEN_API_URL:

During build

These are the environment variables that are only used at the CI level at the moment of building for deployment.

• NETLIFY_ID: Id of the site to be deployed to in Netlify

At the CI itself (Gitlab environment variables)

These are the environment variables set in Gitlab for deployment (see the link in the title):

• NETLIFY_AUTH_TOKEN: Token to deploy to dev and UAT environment's. They are hosted in Alphero's Netlify account.
• NETLIFY_AUTH_TOKEN_PROD: Token to deploy to the prod environment. They are hosted in Smart Payroll's Netlify account. The access for it is available in 1Password under Smart Payroll - Netlify Handover.
• HEROKU_API_KEY: Token to deploy to dev and UAT environment's. They are hosted in Alphero's Heroku account. The access for it is available in 1Password under Alphero Heroku (with [e-mail] as the email).
• HEROKU_API_KEY_PROD: Token to deploy to prod environment. Prod hosted in Smart Payroll's Heroku account.

package.json available scripts

• start: Intended for Heroku to start the app (since it does not allow to change this command, see here).
• start:server: What's used by start (just as a way to try to clarify that start is only intended to the server).
• start:app: Starts the frontend.
• start:server:dev: Starts the server for the development environment. It uses nodemon which can't be used within Heroku (at least that I know of).
• deploy:dev: Deploys the app to the dev environment. Intended for a case where a manual deploy is needed.
• deploy:uat: Deploys the app to the uat environment. Intended for a case where a manual deploy is needed.
• deploy:prod: Deploys the app to the production environment. Intended for a case where a manual deploy is needed.

Deployment scripts

The three deployment scripts work as follows:

• Set the environment variables with the appropriate values for the target environment.
• Build the frontend application
• Update Netlify with the latest build

These sh's call a common deploy.sh which is the one that runs the deployment itself except for deploy-prod.sh which uses a different Netlify Auth Token, since it's a different Netlify account than the rest of the environments.

For the production environment, just to make sure we provide contingency we are currently deploying to two different instances:

• Datacom's infrastructure: Using Datacom's Heroku for the API and Datacom's Netlify for the frontend.
• Smart Payroll's infrastructure: Using Smart Payroll's Heroku for the API and Smart Payroll's Netlify for the frontend.

This is controlled from the gitlab-ci.yml files. There are separate jobs for each the frontend and API for each of the IS's we are using:

• netlify_smartpayroll_prod, netlify_alphero_prod: Deploy the frontend to both Alphero's Netlify and Smart Payroll's Netlify.
• heroku_smartpayroll_prod, heroku_alphero_prod: Deploy the API to both Alphero's Heroku and Smarty Payroll's Heroku.

This contingency only protects us from errors related to domain setups. The CRM API used by both instances is the same. So, any issue related to the CRM not being ready, is not supported by this cuplication.

CI

The CI is set to automatically deploy frontend and backend to Netlify and Heroku respectively.

Depending on the branch the push is made to, the environment that's updated. This is how it's set:

• develop: Deploys to the Develop environment. Intended to provide an easy way to see current progress as things are being developed. Site on Netlify and app in Heroku.

• release/uat: Deploys to the UAT environment. It's where testing will take place. Site on Netlify and app in Heroku.

• master: Deploys to the Production environments. This is where the site will be available to the public. There are two instanes of the app in production.

  • MAIN: Using Smart Payroll's accounts: Site on Netlify and app in Heroku.
  • Contingency: Using on Alphero's accounts: Site on Netlify and app in Heroku.

Table of Contents

• Overview
• Replacing placeholders
• Build Tools and Dependencies
• Installation
• Making commits
• Running the Tests
• Folder Structure
• SCSS Structure
• Code Standards
• internationalisation (i18n)
• Snapshot & Accessibility Testing
• Dev Tools

Overview

This README outlines the details of collaborating and working on Alphero's React Boilerplate. The project is built using React and Redux. Below are details about principles the project follows, getting up and running on your development machine and also includes testing and deployment details.

Replacing placeholders

You will need to find and replace the following placeholder values:

• --APP_TITLE-- The app title
• --PROJECT_NAME-- The project name (may differ from the app title)

Build Tools and Dependencies

The Create React App Guide is extremely detailed and contains some of the information outlined below and more information about enhancing, extending and configuring the build tools.

The default build tools contain:

• React, TSX, Redux, and ES6 syntax support.
• Typescript
• Language extras beyond ES6 like the object spread operator.
• A dev server that lints for common errors.
• The ability to import CSS and image files directly from JavaScript.
• Autoprefixed CSS, so you don’t need -webkit or other prefixes.
• A build script to bundle JS, CSS, and images for production, with sourcemaps.
• An offline-first service worker and a web app manifest, meeting all the Progressive Web App criteria.

Dependency management is split between two main places:

• Build Configuration Dependencies - node_modules/react-scripts/package.json

  • As long as Create React App is not 'ejected', there should be no need to edit this file.
  • The build configuration and dependency list is managed by the Create React App team.
  • Refer to Updating to New Releases for how to update Create React App.
  • If for whatever reason greater configuration control is needed, then refer to Ejecting Create React App for information about manual configuration - Important! please note, this is one way and can't be undone.

• Development Dependencies - ****/client/package.json

  • These are the extra libraries we have added to enable various features and enhancements through development.
  • Installing libraries with npm or npm using the --save or --save-dev flags should automatically update the package.json file.

Installation

Follow the instructions below to pull down the repository.

1. (Might be required) Install nvm curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.34.0/install.sh | bash
2. (Might be required) Install lts version of node: nvm install --lts
3. Run npm install to install dependencies required to run the project.

Running the app, with the Proxy Server

Once the dependencies are installed, in the main project directory, you can run:

npm start

This will run the React app (i.e. the thing in client/) and the API proxy server. Your project may need not need the proxy server, but it can be useful for bypassing browser CORS restrictions and rewriting cookies.

Open http://localhost:8080 to view the React app.

• The page will reload if you make edits.
• You will also see any lint errors in the console.
• This will also start watching for and compiling SASS changes.
• ^C will stop the server if necessary.

Making commits

This project uses the semantic-release npm package to automate changelog and version management in accordance with semver guidelines.

This means that to increment version numbers or add release notes to the changelog, the developer must use a specific commit message format. Each example in the table below increments a different version (major.minor.patch). The notable difference in the last commit is that it simply contains the string BREAKING CHANGE: which causes a major version number bump.

Commit message	Release type
fix(pencil): SIFTER_NUM stop graphite breaking when too much pressure applied	Patch Release
feat(pencil): add 'graphiteWidth' option	Minor Feature Release
perf(pencil): remove graphiteWidth option BREAKING CHANGE: The graphiteWidth option has been removed. The default graphite width of 10mm is always used for performance reasons.	Major Breaking Release

This convention allows for important information to be communicated in the changelog automatically. Test can see sifter numbers of what has been fixed and in which release, and project managers and stakeholders can see which features have been included in which version. Please inspect the package.json scripts of this project to see how the changelog is published to the test environment and hosted alongside the published version.

For further reading see Angular commit message guidelines.

Running Storybook

React Storybook is a UI development environment for React components. With it, you can visualize different states of UI components and develop them interactively. It also serves as a useful reference guide for what components exist in the project for re-use. React Storybook runs outside of the app. So you can develop UI components in isolation without worrying about app specific dependencies and requirements. Once built you can include in the app to customize as per requirements and app data. In a separate terminal tab or terminal window open the client project directory, and run:

npm run storybook

Then you can access your storybook from the browser.

Running the tests

In a separate terminal tab or terminal window open the client project directory, and run:

npm test

Launches the test runner in the interactive watch mode.
See the section about running tests for more information.

Folder Structure

Name	Description
tools/	Build tools, npm scripts etc
.env-cmdrc	JS file which replaces .env used for custom environment variables
.eslintrc.js	ESLint rules
tsconfig.json	TypeScript config
tsconfig.paths.json	TypeScript paths config (may not be needed)
package.json
jest.config.js	Jest config
jest.config.js	ChangeLog generated by semantic-release npm package
.gitlab-ci.yml	GitLab config file for managing CI/CD
docs/	Folder for documents
public/	Anything included here will be automatically included in the build
.storybook/	Storybook related config files
.storybook/config.tsx	Storybook config
.storybook/addons.ts	Storybook addons file
.vscode/	VSCode project settings (recommended extensions, etc)
build/	The build destination folder
src/
src/definitions	TypeScript definition folder for packages that may not contain type definitions
src/styles/	SCSS (AINT) Folder
src/tools/	Folder for tools/utilities/helpers (i18n, analytics, utility/helper functions)

Store	Description
src/store
src/store/main-reducer	The main reducer which imports all the Redux modules
src/store/modules	The folder for Redux modules
src/store/modules/main-saga	The main saga which imports all the Sagas used by modules
src/store/modules/app
src/store/modules/app/actions.ts
src/store/modules/app/api.ts
src/store/modules/app/constants.ts
src/store/modules/app/reducers.ts
src/store/modules/app/sagas.ts
src/store/modules/app/selectors.ts

SCSS Structure

Within the project there is a styles folder that contains AINT CSS which can be extended/edited as appropriate.

Code Standards

This project adheres to the standards laid out by Airbnb's JavaScript Style Guide and React/JSX Style Guide.

It is important to read the information contained in both links to ensure you can code to meet these standards as the Airbnb linting rules are installed as a dependency for the project and will catch code that fails the ruleset.

The pragmatic principles outlined in Clean Code JavaScript are also useful to keep in mind. Semantic code and explicit-ness is preferred.

This project also strives to conform to accessibility standards for document structure and HTML markup. HTML Code Sniffer is a useful JavaScript bookmarklet to help audit the accessibility of the UI.

Snapshot & Accessibility Testing

Within the Jest unit tests there is a utility provided to run an automated accessibility audit via aXe-core, we aim to reach WCAGAA conformance at a minimum and recommend making use of this utility wherever possible (usually shallow mounted components, aXe testing can be difficult with very deep components).

Snapshot testing is also available and you can expect there to be some previously established snapshots within the code base, if you make a minor change, especially to a prop on a component and you run your tests and they return an error similar to Received value does not match stored snapshot you will need to check the snapshot in question, ensure it is correct and update the snapshot via your command line via npm test -- -u.

Any Storybook stories added will automatically generate a snapshot test.

Internationalisation

We use react-intl for internationalisation, it comes with various components and utility functions for things such as printing dates, currency and strings all set to the locale we determine. Please use these utilities wherever possible. All wording should be put into the en-nz.ts (at a minimum, assuming there are no other translation files) with a specifically (yet modular if possible) named key, this means we have a single entry file where we can make simple changes to all strings and internationalise in future if needed.

Dev Tools

Working with any JavaScript framework can be tricky without some ability to inspect what's going on. The following tools are absolute musts:

• React Developer Tools is a Chrome DevTools extension for React. It allows you to inspect the React component hierarchies in the Chrome Developer Tools.
• Redux DevTools is a Chrome DevTools extension for Redux. It allows you to inspect that state held in the global Redux store and track / log actions as they happen in the app.

Browser Support and Polyfills

This project makes use of modern JavaScript features that aren't support in older browsers (e.g. Internet Explorer). Polyfills from the core-js library are used to allow the site to run on older browsers (tested in IE 11, other browsers may require further tweaking).

To avoid bloating the build, polyfills are only added for features that are used. To add a polyfill, find the relevant "CommonJS entry point" in the core-js docs and add it as an import at the very top of client/src/index.js.

CSS features will be automatically prefixed to support the browsers specified in the browserslist section of client/pacakage.json