Oslo kommune ombruk frontend

Table of Contents

• Intro
• Built with
  • Libraries
• Getting started
  • Prerequisites
  • Download project
  • Running locally
• Build and deployment
  • Building and environment variables
• Technology and How to code
  • General
  • Routing
  • Authentication & Role Based Access Control
  • Data fetching and caching
  • User interface
  • Forms
  • Utilities
  • Quality assurance
    • Testing
    • Linting / code formatting
    • Git hooks
• File structure
  • Mocks
  • Public
  • Src

Intro

This is the frontend solution of the reuse station project, belonging to Renovasjon og Gjenvinningsetaten (REG) in Oslo Kommune.

It is a single page application written in React with TypeScript and built with Webpack.

Built with

As mentioned, the application is written in Typescript with React as its framework and Webpack as its build tool. We would recommend reading up on the documentation for both Typescript and React.

In the next section you will see a list with some of the libraries that you may need to read documentation on to understand some of the code base. The rest of the dependencies can be seen in the package.json file in the root folder.

Libraries:

• Chakra UI
• React Router
• Axios
• React Query
• React Hook Form
• Yup
• date-fns
• React Big Calendar
• React Day Picker

A deeper explanation on the technology used can be seen in the Technology section.

Getting started

Prerequisites

To compile and run this project, you would need:

• Node, LTS version (currently v14.16.1)
• Yarn, classic version (v1.22.5 or greater)

Download project

This section will guide you to clone this repository. To follow this part of the guide, we expect you to have Git installed. Type the following lines in the Terminal (for unix users), or Command Prompt (for windows users):

cd /to-your-desired-directory
git clone https://kode.knowit.no/scm/oko/web.git
cd web

You are now inside the project folder. Type ls in the terminal, or dir in Command Prompt to see the root folder structure.

Running locally

Before running/building locally the first time, copy the file .env-sample and rename to .env. The file provides the environment variables required. See "Building and environment variables" below.

• To start the development server simply execute the following in a terminal to install dependencies and run the application:

  yarn install
  yarn start

• Not recommended: it is also possible to use the provided docker container by going into the folder container and executing docker-compose up.

Note: There might be an issue when running the app locally (in the 0.0.0.0 or localhost domain), and connecting to an external Keycloak server. A logged in user might wrongfully be redirected to a logged out page after a certain amount of time. This happens because the web browser identifies the cookie set by Keycloak as from a third party. The problem is solved by disabling the blocking of third-party cookies in the browser. If possible, this should preferably be done by adding a specific rule to allow all cookies from the domain of the Keycloak URL (instructions for Google Chrome).

Build and deployment

The source code is built and deployed to AWS S3 with CI/CD, configured in Bamboo (byggmester.knowit.no).

Three environments are configured in AWS. Each environment is linked to a corresponding branch in the Bitbucket repository. The building process in Bamboo is automatically triggered by creating a pull request to one of these branches. When a pull request is merged, the project is automatically rebuilt and deployed to the correct environment. An exception here is that deployment to the production environment must be triggered manually.

The environments/branches:

• test – for development testing purposes. Pull requests from development branches shall always be made to the test branch.
• staging – for pre-production testing purposes. Only pull requests from the test branch or hotfix branches shall be made to this branch.
• production – running application. Only pull requests from staging shall be made to this branch.

Building and environment variables

The building process is dependent on a set of environment variables (e.g. the correct REST API URL). Webpack is configured with the dotenv-webpack plugin, and the process works as follows:

1. Variables defined in an optional .env file in the root project folder is loaded into the global process.env object. Using .env files are intended for running and building locally.
2. Environment variables from the executing system/CLI session is loaded into the same global object. Matching names with variables from the .env-file is overwritten. Using system environment variables is intended for CI/CD tools (Bamboo).
3. References to process.env.{ENV_VAR_NAME} in the source code is substituted with the environment variable values at build time.

Technology and How to code

General

• React / react-dom – only using functional components and hooks
• Typescript

Routing

• react-router-dom

Authentication & Role Based Access Control

Keycloak is used for authenticating users, and managing user roles.

• keycloak-js: client-side adapter for communicating with the Keycloak server. Documentation can be found here.

  Note: The version of the keycloak-js library is tightly coupled to the version of Keycloak that is running server-side. This means that this library must be updated (only) if the Keycloak server software is updated.

• @react-keycloak/web: Provides a KeycloakProvider component that wraps the entire React application (see App.tsx). The component holds an instance of a Keycloak object (from keaycloak-js), and provides a useKeycloak() hook that can be used to check for authentication and roles in lower level components. See package documentation for details.

Data fetching and caching

• Axios: HTTP client library for doing REST API calls.
• React Query: library used for caching data fetched from REST API. Provides a useQuery() hook for the fetching and caching, and a useMutation() hook to update the data. The cache (contained in a QueryClient instance) has utility methods (like invalidateQueries()) that can be used for interacting with the cache. Documentation can be found here.

User interface

Chakra UI is chosen as the underlying UI component library, which is based on the following benefits:

• Provides common components with base functionality (layout/container elements, form elements, modals, alerts, etc.)
• Components are easily customizable and styleable (using "style props" and theming)
• Simple system for creating responsive styles
• Handles accessibility (for most components - check for "Accessibility" in doc for each component)
• Theming system
• Global CSS reset
• Well documented

Recommended reading:

• Design principles
• Style Props
• Responsive styles
• Theming
  • Customizing theme
  • Styling components
  • Text and Layer styles
  • Global styles
• The sx Prop
• The full list of available components can be found in the documentation

Guidelines:

• We're using fully qualified CSS property names, not the abbreviations (e.g. backgroundColor, not bgColor)
• To customize the styling of predefined library components, we're using the theme system (if possible). Theme files are located in the theme folder.

Forms

• React Hook Form for keeping track of form state.
• yup for performing validation of user input.

Utilities

• date-fns
• lodash

Quality Assurance

Testing

• Jest: testing framework
• ts-jest: transforms .ts and .tsx test files to CommonJS so that Jest can run them. Also provides a mocked() test helper function for fixing typing issues with mocks.
• React Testing Library and jest-dom

Linting / code formatting

• Eslint, with plugins for the following (see .eslintrc.json for details):
  • TypeScript
  • React and React Hooks
  • JSX a11y
  • Testing library and jest-dom
• Prettier
• lint-staged (used by Husky as pre-commit git hook)

Git hooks

• Husky
  • pre-commit: lint-staged
  • pre-push: linting and testing

File structure

Mocks

__mocks__ are mocks for testing and the tests are createt by Jest with react-testing-library and Enzyme.

Public

public consists of all the static files, like index.html.

Src

Inside src are all the source kode for the application, and they are organized in folders and files.

• index and app are the root of the application, like in most React projects.
• assets is where all the images and fonts are stored.
• auth is the folder that consist of all the files used for authentication and roles. keycloak.ts is the file that initialises keycloak.
• components, as the name says, here are the components that are used multiple places.
• pages is a folder that consists of multiple folders for each page in the application. They store their own components and forms if they are specialized for their page.
• routing stores all the files for routing in the application.
• services this is where the queries are done to the database.
• theme, to follow some of the color scheme for this project.
• utils useful function multiple places in the application.