Skip to content

Onboarding

Jump to bottom
Jeffery edited this page Jun 18, 2025 · 24 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.js and pnpm

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 version when you use it.

To install pnpm, simply run corepack enable. This script automatically installs pnpm without having to install it via npm i -g pnpm.

Setting up the codebase

To begin setting up the repository, run pnpm i 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 pnpm 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 pnpm 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 pnpm install <package-name> --filter client <-D>(if dev dependency)
  • To add to the server (backend) run pnpm install <package-name> --filter server <-D>(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. Please use the following commands below:

Client:

cp client/.env.example client/.env

Server:

cp server/.env.example server/.env

Run the dev environment:

Note that you should have set up environment variables already

  • Start both client and server run pnpm dev
  • Start client (frontend) run pnpm dev --filter client
  • Start server (backend) run pnpm dev --filter 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 all packages run pnpm generate:types
  • To generate types for the frontend run pnpm generate:types --filter client
  • To generate routes for the backend run pnpm generate:types --filter server

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 pnpm test. Otherwise find the relative path of the file to test use npx jest <file-name>.

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

  • To test everything in frontend run pnpm 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 pnpm test:firebase requires the emulators installed.

Storybook

To start storybook, run pnpm 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 pnpm --prefix=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 pnpm --prefix=server token to make the uid an admin by default, or call pnpm --prefix=server token <firebase-uid> admin to sign in as an admin.

Clone this wiki locally