Skip to content

Developer Guide

Jump to bottom
zoe | bito edited this page Aug 1, 2026 · 30 revisions

Get Started Working on PV's Website

  1. Observe the basics for github: https://github.com/Progressive-Victory
  2. Refer to README for basic setup instructions: https://github.com/Progressive-Victory/the-website
  3. Pick an issue from the-website issues: https://github.com/Progressive-Victory/the-website/issues
  4. Develop
  5. Make PR from your branch -> dev branch
  6. Contact a tech department lead in discord (#engineering-team or #website-division) for PR review and deployment

Debugging

Browser DevTools

Major browsers contain builtin debugging tools for developers. Use them!

A good resource (though there are probably better ones): https://developer.mozilla.org/en-US/docs/Learn_web_development/Howto/Tools_and_setup/What_are_browser_developer_tools

VSCode

Full VSCode Node debugging setup guide: https://code.visualstudio.com/docs/nodejs/nodejs-debugging

General VSCode debugging guide: https://code.visualstudio.com/docs/debugtest/debugging

Minimal Setup Instructions:

  • Setup .vscode/launch.json, example config:
{
	// Use IntelliSense to learn about possible attributes.
	// Hover to view descriptions of existing attributes.
	// For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
	"version": "0.2.0",
	"configurations": [
		{
			"type": "node",
			"request": "launch",
			"name": "Launch Program",
			"skipFiles": ["<node_internals>/**"],
			"runtimeExecutable": "pnpm",
			"runtimeArgs": ["dev"]
		}
	]
}
  • Configure smart Auto Attach.
  • Set breakpoints.
    • The IDE will pause code execution when it reaches a breakpoint, allowing you to inspect execution step by step later.
  • Start the-website using the debug tab. (Left side, triangle + bug, Ctrl + Shift + D)
  • Now the service is running, and any time a breakpoint is reached in code execution, the debug console should pop up so you can inspect.
    • Trigger breakpoints using the swagger UI (see Testing section in README) or local website actions.
    • Curl is also an option, but less used and supported.

Manual Testing

the-local-setup

We have a repository specifically for local development: https://github.com/Progressive-Victory/the-local-setup

The easiest way to test manually is to follow the setup instructions there. All of the repositories are automatically pulled, with a local mariadb database for dev data. Otherwise, you can set up the other dependencies by following the below instructions.

Connection with the-api

When to connect to local the-api

For projects that interact with the-api and the mySQL database, local testing requires spinning up an instance of the-api as well.

Otherwise, for pure the-website changes, setting up a local the-api is necessary if:

  • testing using browsers other than Google Chrome
  • you refuse to turn off cross-site cookies (which is understandable)

Electro:

The authentication flow uses cookies to track your session. Unfortunately, browsers have a pesky habit of blocking cookies from different domains than your own. Privacy and all that. If both the website and API are on localhost, you're good! If they're both on progressivevictory.win, same! If they're on different origins... not so good. Thankfully, Chrome has no such notion of "privacy", so it's more than happy to keep the cookies. Hooray!

Connecting to local the-api

Follow the-api README and wiki for setup instructions: https://github.com/Progressive-Victory/the-api

Your local the-website connects to your local the-api via the configured environment variable PV_WEBSITE_API_URL in your .env file.

# $PROJECT_DIR/.env
...
PV_WEBSITE_API_URL="http://localhost:8080"

Confirm that the value matches the address printed when the-api starts up.

/home/solar464/scratch/progressive_victory/the-api$ pnpm dev

> pv-api@ dev /home/solar464/scratch/progressive_victory/the-api
> pnpm run build && pnpm run start


> pv-api@ build /home/solar464/scratch/progressive_victory/the-api
> node esbuild.config.js


> pv-api@ start /home/solar464/scratch/progressive_victory/the-api
> node --env-file=.env dist/index.js

{"level":30,"time":1771799363543,"pid":320125,"hostname":"Keter","msg":"Server listening at http://[::1]:8080"}
{"level":30,"time":1771799363544,"pid":320125,"hostname":"Keter","msg":"Server listening at http://127.0.0.1:8080"}
Server listening at http://[::1]:8080

Authentication

If testing functions requiring special permissions like the admin panel, you can give yourself permissions by:

  • Following previous sections to connect to a local the-api instance
  • open Swagger: http://localhost:8080/docs
  • open PATCH /users/{userId}
    • set your userID (which can be found with GET /users/current)
    • set body to { "roles": [1] }

Permutation Testing

This varies based on your project of course, but generally it's worth checking that your feature/UI works on a variety of views.

When starting the-website, the output log should also include the network address. You can access your local instance on any device connected to the same wifi network.

At least test:

  • Desktop (presumably the device you're developing on)
  • Mobile (presumably the device you're procrastinating on)
    • This can be done using your phone, but is easier done on desktop via your browser's devtools

You may also test:

  • different browsers
  • different sizes (resize the browser)
  • different user profile content
    • in the future: use predefined different accounts with varying permissions/data
  • different page magnifications, accessibility layouts

Failing to connect to your locally hosted the-website instance may be caused by:

  • not actually sharing a wifi network
  • incorrect address
  • host device firewalls
  • add more as discovered

Deploy to Preview

While not mandatory, it is possible to deploy branches to preview via Vercel for extra testing by merging to the dev branch.

The preview website url is https://devapi.progressivevictory.win/ and uses a separate dev database.

Do be aware that the dev branch my not be up to date with main, so don't forget to merge main when using it.

FAQ

Formatting

We use prettier! This is applied via the VSCode extension rather than pre-commit since git hooks haven't been setup and the functionality costs money.

In the future we may add scripts to try to automate this.

TODO

Clone this wiki locally