Skip to content
RESN
GitHub

Web App Guide

Contents

The resn-monorepo repo contains the frontend app (https://app.resn.org.au/) and the backend API (https://api.resn.org.au/).

Requirements

To simplify setup, I recommend using either macOS, Linux, or Windows Subsystem for Linux. It is possible to use native Windows, however the below instructions are targeted at UNIX-based systems.

Setting Up

  1. Install Node.js
    • My recommended solution is nvm, as you will be able to update versions easily in the future
    • Run nvm install 18.17.0
    • Run nvm use 18.17.0
    • Test Node.js is installed successfully with node -v
  2. Install pnpm
    • Run corepack enable
    • Run corepack prepare [email protected] --activate
    • Test pnpm is installed successfully with pnpm -v
  3. Install PostgreSQL 15+
    • Follow a guide for your platform (e.g. for Ubuntu)
    • If this is an outdated version, see if you can add a repo for the latest version
    • You can access the SQL CLI with sudo -u postgres psql postgres
    • From the SQL CLI, add a password to the postgres user with ALTER USER postgres WITH PASSWORD 'postgres';
    • From a SQL CLI, run CREATE USER readonly WITH PASSWORD 'readonly';
  4. Install a Git GUI client
    • Recommended: GitKraken or Fork due to cross-platform support, excellent branch visualisation, simple merging, PR visibility, etc
    • Alternative: GitHub Desktop, with fewer features but a simpler interface
  5. Clone the required repository
    • Sign in to the Git client with your GitHub account
    • Clone the resn-monorepo project to a suitable location
  6. Install required dependencies
    • Open a command line within the project directory
    • Run pnpm install from the CLI
  7. Set up environment variables
    • Create a copy of .env.template named .env
    • Ask the Head of Tech for the environment variables on Slack
  8. Clone the database for local development
    • Please see the instructions here
    • Repeat these steps whenever the prod database significantly changes from your local database
  9. Launch the workspace in VSCode
    • Specifically choose Open Workspace from File... and select resn-monorepo.code-workspace
    • This will enable some useful default settings and organise the file navigator

Running Locally

  • To start the project, run the following from the command line: pnpm dev
  • You can run this command from the root folder, or from a specific project (e.g. cd apps/resn-api)
  • Both projects will hot reload when you make edits
  • The frontend app is accessible at http://localhost:5173/
  • The backend API is accessible at http://localhost:5000/

Submitting Your Code

  • Check out our linting instructions here.
  • View the GitHub guide for specifics on creating PRs.

Deploying to Production

  • The project has two GitHub Actions workflows; one called test.yaml and one called deploy.yaml
  • test.yaml will run against all commits, while deploy.yaml must be manually triggered from GitHub Actions once the code is ready for deployment

Key Dependencies

Frontend

  • Svelte:
    • Compiled web framework designed to feel as close to vanilla HTML/CSS/JS as possible, making really powerful functionality easy to learn
    • The rationale between choosing Svelte is explained here
    • The official tutorial is available here
  • SvelteKit:
    • Recommended Svelte metaframework for building sites with routing, SSR, etc.
    • Makes web development an absolute dream
    • The official tutorial is available here
  • Tailwind:
    • Incredible utility CSS classes for building custom designs without needing to write pure CSS
    • Takes away the headache of naming classes, and usually ends up being smaller overall as only necessary CSS is included
    • Tailwind WILL make your life easier if you give it a chance
  • TanStack Query:
    • Handles data fetching and server-state state management
    • Note the React adapter has the most thorough documentation, however most principles are the same for the Svelte adapter
    • Lachlan Collins (former Head of Tech) is the core maintainer for the Svelte adapter
  • Felte:
    • Library which makes forms much easier to manage in Svelte
    • Uses amazing features like stores and Zod to allow for excellent UX+DX
  • Zod:
    • Validation library
    • Primarily used for form validation on the frontend
  • Sentry:
    • Key error-tracking service
    • Please ask the Head of Tech for access to the platform
  • TypeScript:
    • Extends standard JavaScript with static typing
    • Absolute necessity for developing anything beyond a basic hello world
    • A basic introduction is available here
  • ESLint:
    • Finds and fixes problems in JavaScript code
  • Prettier:
    • Opinionated code formatting for JavaScript

Backend

  • Express:
    • Kind-of-ancient NodeJS framework
    • Barely used as it is just a wrapper to use tRPC
  • tRPC:
    • The best way I’ve found to develop full-stack type-safe projects while still keeping the frontend and backend in separate codebases
    • More detailed explanation here
  • Prisma:
    • Powerful SQL ORM with great TypeScript generation
    • More detailed explanation here
  • Zod:
    • Validation library
    • Primarily used to validate endpoint inputs
  • Handlebars:
    • Simple email templating framework
  • Sentry:
    • Key error-tracking service
    • Please ask the Head of Tech for access to the platform
  • TypeScript:
    • Extends standard JavaScript with static typing
    • Absolute necessity for developing anything beyond a basic hello world
    • A basic introduction is available here
  • ESLint:
    • Finds and fixes problems in JavaScript code
  • Prettier:
    • Opinionated code formatting for JavaScript