Skip to content
RESN
GitHub

Public Site Guide

Contents

The resn-www repo contains the public website (https://www.resn.org.au/). It is built to be as performant and SEO-friendly as possible, and showcases our service to the broader public.

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 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
  4. Clone the required repository
    • Sign in to the Git client with your GitHub account
    • Clone the resn-www project to a suitable location
  5. Install required dependencies
    • Open a command line within the project directory
    • Run pnpm install from the CLI
  6. Set up environment variables
    • Create a copy of .env.template named .env
    • Ask the Head of Tech for the environment variables on Slack
  7. Launch the workspace in VSCode
    • Specifically choose Open Workspace from File... and select resn-www.code-workspace
    • This will enable some useful default settings and organise the file navigator

Running Locally

  • To start the app, run the following from the command line: pnpm dev
  • The app will hot reload when you make edits
  • The site is accessible at http://localhost:5173/

Submit 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 Packages

  • 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
  • Melt UI:
    • A collection of excellent headless utilities to create accessible components (e.g. accordions, dialogs, etc.).
    • Library is still in beta development, but is far better than existing headless component solutions
  • Contentful:
    • Package to interact with our Contentful CMS
    • Still on v9 since there were some major changes in v10
    • Package controversially still uses Axios which means that edge runtimes won’t work
  • Histoire:
    • Very lightweight and simple “stories” solution (demoing components)
    • Similar to Storybook, but that wasn’t available for SvelteKit at the time
  • 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