Getting Started with Front-end Development

This page will show you how to contribute to MetaGrid's front-end. You'll learn about the technologies used, the file structure scheme, and the style guide. Resources are also provided to get new contributors up to speed in the technologies.

Technologies

Core

React UI Library

Formatter and Linter

Testing/QA

DevOps

File Structure

Adapted from sources:

Root

frontend
├── .envs
│ └── .react
├── docker
│ ├── local
│ └── production
├── public
│ ├── favicon.ico
│ ├── index.html
│ └── manifest.json
├── src
│ ├── api
│ │ ├── mock
│ │ │ ├── fixtures.ts
│ │ │ ├── server-handlers.test.ts
│ │ │ ├── server-handlers.ts
│ │ │ ├── server.ts
│ │ │ └── setup-env.ts
│ │ ├── index.test.ts
│ │ ├── index.ts
│ │ └── routes.ts
│ ├── assets
│ │ └── img
│ ├── common
│ │ ├── JoyrideTour.test.ts
│ │ ├── JoyrideTour.ts
│ │ ├── reactJoyrideSteps.test.ts
│ │ ├── reactJoyrideSteps.ts
│ │ ├── TourTargets.test.ts
│ │ ├── TourTargets.ts
│ │ ├── types.ts
│ │ ├── utils.test.ts
│ │ └── utils.ts
│ ├── components
│ │ ├── App
│ │ │ ├── App.css
│ │ │ ├── App.tsx
│ │ │ └── App.test.tsx
│ │ ├── Cart
│ │ └── ...
│ ├── contexts
│ │ ├── AuthContext.test.ts
│ │ ├── AuthContext.tsx
│ │ ├── ReactJoyrideContext.test.ts
│ │ ├── ReactJoyrideContext.tsx
│ │ └── types.ts
│ ├── lib
│ │ ├── axios
│ │ │ ├── axios.d.ts
│ │ │ └── index.ts
│ │ ├── keycloak
│ │ │ └── index.ts
│ ├── test
│ │ └── custom-render.tsx
│ ├── env.ts
│ ├── index.css
│ ├── index.tsx
│ └── setupTests.ts
├── .dockerignore
├── .eslintrc.js
├── .gitignore
├── .prettierignore
├── .prettierrc
├── docker-compose.prod.yml
├── docker-compose.yml
├── package.json
├── README.md
├── tsconfig.json
└── yarn.lock
  • .envs/ - stores environment variables for each microservice found in the docker-compose files.
  • docker/ - stores files used by each microservice found in the docker-compose files, including DockerFiles, start scripts, etc, separated by environment and service
  • public/ - stores static files used before app is compiled https://create-react-app.dev/docs/using-the-public-folder/#when-to-use-the-public-folder
  • src/ - where dynamic files reside, the bulk of your work is done here
    • api/ - contains API related files
      • mock/ - API mocking using mock-service-worker package to avoid making real requests in test suites. More info here
        • fixtures.ts - stores objects that resemble API response data
        • server-handlers.ts - handles requests to routes by mapping fixtures as responses to each route endpoint
        • server.ts - sets up mock service worker server with server-handlers for tests. Essentially, it creates a mock server that intercepts all requests and handle it as if it were a real server
        • setup-envs.ts - imports the mock service worker server to all tests before initialization
      • index.ts - contains promise-based HTTP client request functions to APIs, references routes.ts for API URL endpoints
      • routes.ts - contains routes to APIs and error-handling
    • assets/ - stores assets used when the app is compiled
    • common/ - stores common code used between components such as utility functions
    • components/ - contains React components and related files. Follow React Components File Structure
    • contexts/ - stores React Context components, such as for authentication state
    • lib/ - stores initialized instances of third party library that are exported for use in the codebase (e.g. Axios, Keycloak)
    • test/ - contains related files and functions shared among tests
      • custom-render.tsx - wraps the react-testing-library render method with contexts from /context
    • env.ts - converts environment variables into constants for reusability
    • setupTests.ts - configuration for additional test environment settings for jest
  • .dockerignore - files and folders to ignore when building docker containers
  • eslintrc.js - configuration file for ESLint
  • .prettierignore - files and folders to ignore when running prettier
  • .prettierrc - configuration file for prettier
  • docker-compose.prod.yml - the production build of docker-compose
  • docker-compose.yml - the local development build of docker-compose
  • tsconfig.json - configuration file for TypeScript
  • yarn.lock - the purpose of a lock file is to lock down the versions of the dependencies specified in a package.json file. This means that in a yarn.lock file, there is an identifier for every dependency and sub dependency that is used for a project

React Components

What are React Components?

Below is an example of how MetaGrid scaffolds React components.

frontend
└── src
    └── components
        ├── AComponentWithoutChildren.tsx
        └── Facets
            ├── FacetsForm.test.tsx
            ├── FacetsForm.tsx
            ├── index.test.tsx
            ├── index.tsx
            ├── ProjectForm.test.tsx
            ├── ProjectForm.tsx
            └── types.ts

File Naming

  • React component file names should be PascalCase, descriptive, and relate to the parent component if applicable
  • Use named exports over default exports to make searching easier

Grouping/Nesting

  • Use a folder to nest child components related to a parent component (e.g. FacetsForm.tsx is under Facets)

  • Use index.tsx as the file name for the parent component in the group components. This allows you to import the component just by referencing the folder.

    • If you named the parent component Facets.tsx, you have to import using: import Facets from '../Facets/Facets.tsx'; Avoid this.
    • Otherwise, you avoid redundancy by naming the parent component index.tsx: import Facets from '../Facets';
  • Why not nest child components even further in their own directories? Because too much nesting makes the /components directory complicated to navigate.

Test Files

  • Each testable file and component typically has an associated .ts/.tsx file (e.g. FacetsForm.test.tsx). This is determined by what you need to test via the code coverage report.

Style Guide

The MetaGrid front-end follows the Airbnb JavaScript and React/JSX style guides. Please spend some time to read through the style guides.

Style guide and linting rules are enforced in CI test builds.

Useful React Commands

Run a command inside the docker container:

docker-compose -p metagrid_frontend_dev run --rm react [command]

yarn start:local

Runs the app in the development mode using .local environment settings.
Open http://localhost:3000 to view it in the browser.

The page will reload if you make edits.
You will also see any lint errors in the console.

yarn start:production

Runs the app in the development mode using .production environment settings.
Open http://localhost:3000 to view it in the browser.

The page will reload if you make edits.
You will also see any lint errors in the console.

yarn test

Launches the test runner for a single run without coverage report.
See the section about running tests for more information.

yarn test:coverage

Launches the test runner for a single run with coverage reporting.
See the section about running tests with coverage for more information.

yarn test:watch

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

yarn lint

Runs linters to display violations.

yarn precommit

Runs linters against staged git files and attempts to fix as many issues as possible.
https://github.com/okonet/lint-staged

yarn run build:local

Builds the app for production to the build folder using .local environment settings.
It correctly bundles React in production mode and optimizes the build for the best performance.

The build is minified and the filenames include the hashes.
Your app is ready to be deployed!

See the section about deployment for more information.

yarn run build:production

Builds the app for production to the build folder using .production environment settings.
It correctly bundles React in production mode and optimizes the build for the best performance.

The build is minified and the filenames include the hashes.
Your app is ready to be deployed!

See the section about deployment for more information.

New Contributor Resources

Here are some resources to get you up to speed with the technologies.

Documentation

Courses

Tutorials and Cheatsheets