Skip to content

Latest commit

 

History

History
257 lines (189 loc) · 14.6 KB

README.md

File metadata and controls

257 lines (189 loc) · 14.6 KB
Raw

Oslo kommune ombruk frontend




Table of Contents

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:

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:

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

Routing

Authentication & Role Based Access Control

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

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:

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

Quality Assurance

Testing

Linting / code formatting

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.