Skip to content

Onboarding

Jump to bottom
Benson Cho edited this page Jul 31, 2024 · 22 revisions

If you are going to be developing, this is the right place to start.

Getting Started

Cloning the repository

To clone repo, run git clone https://github.com/UoaWDCC/uasc-web.git. Make sure you have git installed (check by running git --version in a terminal).

Installing node and yarn

We are using Node version 20.3

It is recommended to use volta to manage your Node and Yarn version. Install it with:

  • Windows
  • Mac/Linux/WSL: curl https://get.volta.sh | bash

Volta will automatically install the correct node and yarn version when you use it.

Setting up the codebase

To begin setting up the repository, run yarn at the root (the directory that contains README.md). This will install all the dependencies used for this project.

If you are using VS Code run yarn vsc-setup which will install the ESLint and Prettier vscode extensions. Other environments like nvim please refer to relevant documentation to set this up. Setting up auto formatting is recommended (for VSC: File > Preferences > Settings > Text Editor > Formatting)

We are using yarn workspaces so if you want to (run all these commands from the root if possible):

Add any packages:

  • To add to the client (frontend) run yarn workspace client add <package-name> <--dev>(if dev dependency)
  • To add to the server (backend) run yarn workspace server add <package-name> <--dev>(if dev dependency)

Setting up secrets:

These are configurations required to run the application. The files you need are (exact file names):

  • server/.env
  • client/.env

See the templates at the bottom of the page for the env file setup.

IMPORTANT: They are called secrets for a reason! So, if you need them, please contact any of the 2024 contributors, and they should be shared through something like privnote.

ENV File format

You will have to create a file called .env in both the /client and /server directories. Paste the relevant templates in and obtain the secrets.

Client:

NEXT_PUBLIC_FIREBASE_API_KEY=
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=
NEXT_PUBLIC_FIREBASE_PROJECT_ID=
NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET=
NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=
NEXT_PUBLIC_FIREBASE_APP_ID=
NEXT_PUBLIC_BACKEND_BASE_URL=http://localhost:8000/
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=
NEXT_CONFIG_ENV=

Server:

API_KEY=
USER_ID=
GOOGLE_SERVICE_ACCOUNT_JSON=
STRIPE_API_KEY=
FRONTEND_URL=
NODE_MAILER_EMAIL=
NODE_MAILER_PASSWORD=

Run the dev environment:

Note that you should have set up environment variables already

  • Start client (frontend) run yarn dev-client
  • Start server (backend) run yarn dev-server

Pre push hooks

We use husky to run linters and formatters on each push to help ensure that code quality is maintained before pushes. These will be done automatically, however if your device is trash slow then it is acceptable to add --no-verify to the end of your git push. Note that pushing failing code will not allow you to merge, so it is recommended to let them run.

Code generation

We make use of openapi-typescript to create types for the frontend (based on swagger.json) when calling our backend API and tsoa to automatically generate routes for our express application and create a swagger.json.

  • To generate types for the frontend run yarn workspace client generate-types
  • To generate routes for the backend run yarn workspace server tsoa spec-and-routes

Note: this is automatically handled when running the dev commands

Automated Testing

Jest

Testing is handled with jest and tests should be written where possible

  • To test everything, run yarn test. Otherwise find the relative path of the file to test use npx jest <file-name>.

  • To test everything in backend run yarn test-server (IMPORTANT if you do not have firebase emulator running!)

  • To test everything in frontend run yarn test-client

Emulators

Make sure you have firebase cli installed globally with npm install -g firebase-tools and run firebase emulators:start. For our case we will not be using the emulators much (we have a staging project) but yarn firebase-test requires the emulators installed.

Storybook

To start storybook, run yarn storybook.

Generate tokens

When testing the REST API bearer authentication is required. The Swagger UI (at localhost:8000/api-docs) has an authentication option. image image

To get a token, run yarn workspace server token <firebase-uid> where <firebase-uid> is the user id of the user you want to sign in as (you can obtain from firebase console for the staging instance).

Note

The above applies if you want to have a non-admin user

Alternatively set the USER_ID key in server/.envand simply call yarn workspace server token to make the uid an admin by default, or call yarn workspace server token <firebase-uid> admin to sign in as an admin.

Clone this wiki locally