Table of Contents
Listed below are the main frameworks/libraries used to build this website.
Listed below are the testing frameworks and libraries used to write automated tests.
To get this project set up locally, go through the steps below.
- Visual Studio Code is not required for this project but is recommended. You can download VS Code from here.
- Clone the repo
git clone [email protected]/taylorblankenshipwt/buttercup.git
- Install NPM packages
npm install
To run the development server:
npm run devOpen http://localhost:3000 with your browser to see the result.
To create a static build:
npm run buildCheck the out directory to see all of the build artifacts.
To run the linters on your project:
npm run lint # Runs ESLint on Typescript and React files
npm run lint:style # Runs Stylelint on .scss files
npm run lint:all # Runs both ESLint and Stylelint on your project filesTo run all unit tests:
npm run testTo run typechecks:
npm run typecheckA shared directory has been established to maintain test ID constants that can be used across the FE tests.
When creating a unit test that requires test IDs, use the import statement
import { TestIDs } from 'shared/TestIDs'
to pull in a class instance with all declared test IDs. Test IDs within the class are grouped into objects based on components, with properties that represent elements within the component. For example: TestIDs.DoggyLink.DoggyLinkName should reference the declared test ID for the name field within DoggyLink.
When tagging a TSX element with a test ID, use the import statement
import { assignTestID } from 'shared/TestIDs'
to pull in a function that returns a test ID attribute. The assigned value is type-enforced so that the argument must be the key for a declared test ID in the TestIDs class. The syntax for assigning a test ID looks like this:
<div {...assignTestID('DoggyLinkName')} />
Mango's Web platform currently supports three different environments: Local, Development, and Production. Deployed version of Production environment can be found at buttercup.vercel.app/. The Local environment can be accessed by running npm run dev on your machine, then navigating to http://localhost:3000.
Local is the version of the application that can be run locally; no formal build or deployment process is necessary. It tends to be used mainly when doing local branch testing prior to PR merges to develop.
Development is the most up-to-date version of the codebase, with features from both past releases and upcoming releases. All work must go through Development in order to be eventually added to Production.
Production is a collection of released features; all work added to Production is stable enough to be user-facing.
Currently data across all three environments is the same, sourced from the same data lake.
Merges to the develop branch lead to automated deployments to the Development environment, while merges to the main branch result in deployments to the Production environment.
In order to successfully merge to Development, the to-be-merged code must pass all validation checks. To merge to Production, the develop branch must first successfully build and deploy to Development.
There are four existing pipelines that use GitHub Actions: PR Validation, Run PR Branch Name Check, Vercel Preview Deployment (for Develop), and Vercel Production Deployment (for Production).
Branch protections have been configured so that PR Validation will run on any PRs attempting to merge changes into develop. It runs unit testing, linting checks, and type checks. Failure of any validation checks will throw an error and prevent the merging of the tested branch.
Run PR Branch Name Check runs on creation of a PR that is merging into main. Its purpose is to prevent accidental merges of untested code into production.
Vercel Preview Deployment and Vercel Production Deployment run on merges to develop and main respectively. They deploy the site to their intended environments.
Mango’s develop and main branches represent Development and Production, with feature work being implemented and added to the develop branch, and eventually released via the main branch.
When a new release is ready to be cut, a new PR should be created to merge the develop branch into the main branch.
- Create a PR to merge
developintomain. - When the PR is approved and has passed all required checks, merge all commits.
Congrats! You’ve completed the release.
Following the merge into main, GitHub automatically displays a banner stating main has had recent changes. Do not attempt to merge main’s changes back into develop. The banner can be ignored.
This document describes some of the common patterns we follow when creating React components, including how we structure the components/ directory and important files that should be included for each component you make. Within this directory, you can also find example React components that demonstrate the patterns explained here.
File Naming Pattern:
ComponentName.tsxExamples:
Component without props:templates/ComponentWithoutProps/ComponentWithoutProps.tsx
Component with props:templates/ComponentWithProps/ComponentWithProps.tsx
React is a JavaScript library we use for building our user interface. It allows us to compose complex UIs from small and isolated pieces of code called "components". In this project you will find all of our components in the components/ folder.
Looking in the components/ folder, you will see a set standard for how to struture your component. Each component has its own folder with the folder and its files named using Pascal Case.
A component folder should resemble the following:
Example.tsx- The React component itselfExample.module.scss- The styles for the componentExample.test.tsx- Unit tests for the componentindex.ts- The component export for cleaner import statements
You may find a helpers.ts file in some of the components. These helper files can be used for keeping as many helper functions used by your component as you need to keep the component file clean.
File Naming Pattern:
ComponentName.module.scssExamples:
Component without props:templates/ComponentWithoutProps/ComponentWithoutProps.module.scss
Component with props:templates/ComponentWithProps/ComponentWithProps.module.scss
CSS Modules are CSS files in which all class names and animation names are scoped locally by default. The class and animation names are automatically generated to be unique so that you don't have to worry about selector name collisions.
SASS is a CSS pre-processor. It is advanced syntax that allows the use of features not available in CSS that is processed and compiled into regular CSS for the browser to consume.
Using CSS Module with SASS is one of the most widely used combinations of web styling architecture and it allows us to create clean, reusable CSS. There are a few patterns used on this project to be aware of.
Functions and mixins are features of SASS that allow you to define styles or complex operations that can be re-used throughout the website. Functions are defined using @function and used in a styles file using the normal CSS function syntax. Mixins are defined using @mixin and used in a styles file using @include.
Our functions and mixins live in the globalStyles folder, globalStyles/mixins.scss, along with a short description of what each does.
To use a function or mixin, make sure you import the file with @import 'globalStyles/mixins'. If you try to use any without the import, the compiler will not throw an error and the mixin or function will not work.
Another feature of SASS we utilize is SASS variables. They allow you to assign a value to a name that begins with $, and then refer to that name instead of the value itself. We use SASS variables to define our project colors and breakpoints. These can be found in globalStyles/variables.scss and must be imported with @import 'globalStyles/variables' to access any variable you want to use in a styles file.