sg1-platform

SG1

This node package enables developers to build micro-frontend platforms using React. Inspired by micro-service architectures, this approach splits the front-end into separate modules to be developed and deployed independently from one another.

Table of Contents

• Maintainers
• Overview
  • Architecture
  • Dependencies
  • Terminology
• Deployment and Configuration
  • Environment Variables
  • Metrics and Telemetry
  • Logging
  • Analytics
  • Versioning
  • CI/CD
• Developer Details
  • Installation
  • File Linting
  • Git, Pull Requests, and Reviews Process
  • Testing
  • Resources
  • Environments
  • Deployment
  • Unit Testing

Maintainers

• Hugh Boylan
• David Gottlieb

Overview

SG1 was inspired by Shipt's desire to migrate from a monolith application to one which could easily be maintained by devlopers across many teams. After searching for the right solution, we found that there really weren't any good approaches in the developer community for solving this problem and decided to build SG1. It is comprised of popular, open-source frameworks to help teams of developers rapidly build applications using a modular, micro-frontend architecture.

Architecture

The SG1 platform is comprised of several node packages with @shipt/sg1 at its core.

Dependencies

• @okta/okta-react
• @shipt/nova
• axios
• react-router-dom
• styled-components

Terminology

• SG1 App: Core application which loads and renders SG1 modules at runtime.
• SG1 Module: Discrete bundle of code which can be loaded by SG1 and rendered.
• Nova: Component, state management, and interface library.
• Module Context
  • ID: The unique module identifier for a given SG1 namespace.
  • Menu: The menu structure includes all menu items that should be displayed in the SG1 navigation. Each menu item in this collection includes the name, the route and sort order.
  • SubRoutes: The sub routes are any route that your module needs to use and that SG1 should have knowledge of but doesn't need to display in the menu. (e.g. An edit product page /product/34433/edit).
• Module CDN: Where all compiled SG1 modules are hosted and loaded from at runtime.

Deployment and Configuration

Environment Variables

The following environment variables must be set in SG1 Apps.

Name	Default	Description
REACT_APP_CDN	https://sg1-modules.staging.shipt.com	Domain hosting SG1 modules
REACT_APP_SITE_ROOT	http://localhost:3000	Application domain
REACT_APP_LOCALHOSTS	[]	Alternate domains hosting SG1 modules (JSON array)
REACT_APP_OAUTH_URL	https://shipt.okta.com	Okta OAuth URL
REACT_APP_OAUTH_ISSUER	https://shipt.okta.com/oauth2/aus4lad0y7z7crJyw2p7	Okta OAuth issuer
REACT_APP_OAUTH_CLIENTID	0oa4ejb77uZEbODj92p7	Okta OAuth client ID

Note: .env files are supported via CRA

Metrics and Telemetry

N/A

Logging

N/A

Analytics

N/A

Versioning

Semantic Versioning (SemVer) is used when publishing to NPM.

CI/CD

• Drone
  • Clone
  • NPM Install
  • NPM Test
  • NPM Build
  • Upload codecov

Developer Details

Installation

SG1 Package Developers

1. git clone [e-mail]:shipt/sg1.git
2. cd sg1
3. npm install
4. npm test

SG1 App Developers

1. Generate new SG1 apps using our custom CRA scripts and template.

npx create-react-app SG1_APP_NAME \
--scripts-version @shipt/sg1-scripts \
--template @shipt/sg1

1. cd SG1_APP_NAME
2. Create a .env file with the required env vars.
3. npm start
4. open http://localhost:3000

SG1 Module Developers

1. Generate new SG1 modules using our custom CRA scripts and template.

npx create-react-app SG1_MODULE_NAME \
--scripts-version @shipt/sg1-module-scripts \
--template @shipt/sg1-module

1. cd SG1_MODULE_NAME
2. npm start
3. open http://localhost:5000/manifest.json

File Linting

ESLint + Prettier is used to lint and format Typescript code according to both Shipt and the React community's best practices.

VS Code users can take advantage of the Prettier extension to automatically fix lint errors on save.

code --install-extension esbenp.prettier-vscode

Git, Pull Requests and Reviews Process

The master branch is default and feature branches should be created from it for all development.

1. git checkout master
2. git pull origin master
3. git checkout -b GH_USER/PR_TASK/PR_FEATURE_DESCRIPTION

Testing

Jest + React Testing Library is used to verify component functionality.

Resources

• Nova
• Okta React SDK
• Jest
• React Testing Library
• Styled Components

Environments

SG1 itself is published as a Node package via @shipt/sg1.

SG1 Applications

Simply build, deploy, and host the SPA as you normally would.

SG1 Modules

There are a few strings that need to be pulled to get your module into production.

SG1 is driven by a manifest that contains the module name, references to the module context and the module itself.

To deploy your module to production, those items need to be added to the manifest file. To eliminate the requirement of a human having to make changes to the manifest file, the CI process will inject that information into the manifest when a merge occurs to the master branch.

Deployment

Ensure your project's root directory contains a .npmrc file with the latest npm token. This is required to allow private repositories to be installed in the DevOps pipeline. Check here for the latest version.

Using this as a reference build your .drone.yml. Then I would recommend dropping the following message in the #ask-devops:

Would someone be a lamb and review the .drone.yml to be sure it is set up correctly for my module to go to production? Could you also initialize Drone for our SG1 module repo module repo url here

One Drone is initialized and your .drone.yml file is set up correctly, any merges to the master branch will trigger a new build of your module and deployment to production SG1.

Unit Testing

Code coverage should never decrease. The metrics for this are here.