chore: dev setup process improvements

CONTRIBUTING.md

@@ -2,49 +2,148 @@
 
 ## Overview
 
-Hello there! In order to simplify the process of contributing, we're putting this document together. This repo serves as the build point for the [ficsit.app](https://ficsit.app) application. To extend or enhance the main site, you'll need to fork and open a PR.
+Hello there! In order to simplify the process of contributing, we've put this document together.
+This repo serves as the build point for the [ficsit.app](https://ficsit.app) application.
+To extend or enhance the main site, you'll need to fork and open a PR targeting the `staging` branch.
 
 ## Requirements
 
 At the highest level you must at least have:
 
 * [NodeJS](https://nodejs.org/en/)
-* [pnpm](https://pnpm.io/)
-* terminal (Bash is suggested but not required.)
+  * Check [`.github\workflows\push-base.yml`](.github/workflows/push-base.yml)'s `NODE_VERSION` to see which Node version to use.
+  * [Node Version Manager](https://github.com/nvm-sh/nvm) (Unix)
+    or [nvm-windows](https://github.com/coreybutler/nvm-windows) (Windows)
+    is suggested if you plan to have multiple Node versions installed.
+* Bash
+  * You must use Git Bash on windows for environment variables to be handled correctly.
 
-### pnpm installation
+### pnpm Installation
 
-This project uses `pnpm`. To install `pnpm` run:
+This project uses `pnpm`.
+If you don't already have it installed, run the following to install `pnpm`:
 
 ```sh
-$ npm i -g pnpm
-...
-1 package is looking for funding
+npm i -g pnpm
+```
+
+The expected output is:
+
+```text
+<a whole bunch of messages about packages being installed>
+<some number of> packages are looking for funding
   run `npm fund` for details
 
-found 0 vulnerabilities
+found <some number of> vulnerabilities
 ```
 
-After that run:
+## Local Setup
+
+### Package Installation
+
+Every time you pull changes or switch branches, make sure you have the correct packages installed for that commit.
+Run this command from a terminal window opened inside the **repository's root directory**:
 
 ```sh
-$ pnpm i
-...
+pnpm install
+```
+
+The expected output is:
+
+```text
+<a whole bunch of messages about packages being installed>
 > husky install
 
 husky - Git hooks installed
+
+Compiling SMUI Styles...
+Writing CSS to static/smui.css...
+Done in <some number>s
+```
+
+### Decide Which Environment You Want To Run
+
+This project has three main environments:
+
+* `production`
+  * Deployed on the ficsit.app site, you probably want to use this if you're running or previewing the main branch
+* `staging`
+  * Deployed on the ficsit.dev site, features get merged in here first before being sent to main.
+* `development`
+  * Used if you'd like to run the [backend](https://github.com/satisfactorymodding/smr-api) yourself (which most likely you don't)
+
+If you do not specify which environment you want to use when running `pnpm` comands, `development` will be used by default.
+
+### Loading Environment Variables
+
+This project uses dotenv-flow to simplify the process of handling environment variables.
+It will handle the loading of the contents of the `.env.something` files for you when running `pnpm` commands,
+provided that you prefix the command with a specifier for which environment to use.
+
+If you don't wish to run the backend (which most likely you don't),
+you can point your local frontend to the staging or production APIs using environment variables:
+(note this example env var syntax only works in bash)
+
+```shell
+NODE_ENV=staging YOUR_COMMAND_HERE
 ```
 
-Now you're good to go!
+or
+
+```shell
+NODE_ENV=production YOUR_COMMAND_HERE
+```
 
-## Local Development
+You can make your own `.env.something.local` files if you need to point to a different API
+or have a different local configuration.
 
-See the [Readme](README.md) for how to point your local frontend to the staging or production API.
+#### Troubleshooting
 
-After you've installed everything, start the project via:
+If for some reason dotenv-flow isn't working for you,
+you can use the following bash script to load the environment variables.
+Replace `staging` with the suffix of the env file you wish to use.
 
 ```sh
-$ pnpm run dev
+export NODE_ENV=staging; set -o allexport; source .env.staging; set +o allexport
+```
+
+After running this command, all commands you run in that bash session will have those environment variables loaded.
+
+### Downloading Translations
+
+This project uses Tolgee to manage translations.
+The project will fail to build if you don't download the translation data files.
+
+Download the latest strings via the `translations` script.
+
+For example:
+
+```shell
+NODE_ENV=staging pnpm run translations
+```
+
+If it errors, try following the troubleshooting steps above to load environment variables manually.
+
+### Starting the Local Server
+
+After you've installed everything, start the project via the `dev` script.
+It executes several smaller scripts for you:
+
+* Development Server with hot reload (dev:serve)
+* Svelte Checker with hot reload (check:dev)
+* GraphQL Code Generator with hot reload (graphql-codegen:watch)
+* ESLint with hot reload (lint:dev)
+
+Run the dev script via `pnpm dev`.
+For example:
+
+```shell
+NODE_ENV=staging pnpm dev
+```
+
+The expected output is:
+
+```text
 ...
 
   SvelteKit v1.0.0-next.87
@@ -56,25 +155,55 @@ $ pnpm run dev
   Use --host to expose server to other devices on this network
 ```
 
-And head to [localhost:3000](http://localhost:3000) to see it running.
+Head to [localhost:3000](http://localhost:3000) to see it running.
+
+If you see any GraphQL messages about network errors,
+you probably need to change what environment variables you're using.
+
+### Signing In
+
+Getting signed in on your locally hosted copy requires copying a login token from the live `https://ficsit.dev` site.
+It's not possible to use the Sign In button on your locally hosted copy
+because the authentication service will reject the request
+since it's coming from `localhost:3000` and not the live site.
+Trying to use the button will direct you to the `https://ficsit.dev` site with an error message encoded in the URL.
 
-If you need to sign in, use the login button which will eventually redirect you to `ficsit.dev`. Then copy the `token` cookie over (like from Chrome dev tools -> Application -> Cookies) and insert it in your `localhost:3000` page (again using dev tools) and refresh.
+In order to sign in:
+
+1. Have a local copy of the frontend running already (ex. via `NODE_ENV=staging pnpm dev`)
+2. Sign in as normal on `https://ficsit.dev`
+3. Access your brower's stored cookie data
+    * Chrome: dev tools -> Application -> Cookies
+    * Firefox: dev tools -> Storage -> Cookies
+4. Copy value of the `token` cookie. If it doesn't exist, make sure you're actually signed in.
+5. Go back to your locally hosted copy (ex. `https://localhost:3000`)
+6. Return to the browser's stored cookie data
+7. If the `token` cookie exists, replace its value with the value you copied.
+   If the cookie doesn't exist yet, create a new cookie, rename it to `token`, and set its value to the value you copied.
+8. Force refresh the page, after which you should be logged in after it loads (might take a second or two)
+
+To sign out, either use the Logout option on the site, or delete the cookie.
 
 ## Committing Changes
 
 Our repo is designed to help you throughout your contribution to maintain our code and commits in a way that allows for automatic deployment. To that end we have a few steps that occur for each change you submit.
 
-You may need to run `pnpm format` to format your code before it will pass the commit hooks
-because the linters cares about file line endings and Git may switch them around on you.
-
 ### On Your Local
 
-When your changes are ready to be committed, we do a few things:
+When your changes are ready to be committed, we do a few things for you:
 
   1. we run `pnpm lint` to validate your syntax
   1. we run `pnpx svelte-check` to validate all of your svelte
   1. we validate your commit adheres to our `commitlint` conventions
 
+#### What You Need To Do
+
+Committing will be blocked if your changes does not pass the linters mentioned above.
+Running `pnpm format` will attempt to auto-fix most style issues.
+
+Note that Git may switch around file line endings on you, causing the linters to fail on files you never edited.
+Running `pnpm format` will fix this.
+
 ### In The Remote
 
 When you've opened up your Pull Request we do a few more things:

README.md

@@ -1,44 +1,15 @@
 # SMR Frontend
 
-## Development
+Frontend for the Satisfactory Mod Repository.
+Implemented via NodeJS, Typescript, Svelte, GraphQL, and SMUI.
 
-See [Contributing](CONTRIBUTING.md) for more information.
-
-### Setup
-
-This project uses [pnpm](https://pnpm.js.org/):
-
-```shell
-pnpm install
-```
-
-After switching branches you should regenerate the graphql files as the schema may have changed:
-
-```shell
-pnpm graphql-codegen
-```
+## Contributing
 
-### Running
+Contributions are welcome and encouraged.
 
-The `dev` script executes several processes:
-
-* Development Server
-* Svelte Checker
-* GraphQL Code Generator
-* ESLint
-
-```shell
-pnpm dev
-```
-
-If you don't wish to run the backend (which most likely you don't),
-you can point your local frontend to the staging or production APIs using environment variables:
-(note this example env var syntax only works in bash)
+See [Contributing](CONTRIBUTING.md) for more information.
 
-```shell
-NODE_ENV=staging pnpm dev
-NODE_ENV=production pnpm dev
-```
+## Setup, Development, Running
 
-You can make your own `.env.something.local` files if you need to point to a different API
-or have a different local configuration.
+To avoid duplicating information, all setup and development information is included in the contributing guide.
+See [Contributing](CONTRIBUTING.md) for more information.

download_translations.sh

@@ -1,7 +1,32 @@
 #!/usr/bin/env sh
 
+display_error() {
+    echo "$1 is not defined, are you sure you correctly loaded the environment variables for the environment you wish to download translations for?"
+    exit 1
+}
+
+if [[ -z "${PUBLIC_TOLGEE_API_URL}" ]]; then
+    display_error "PUBLIC_TOLGEE_API_URL"
+else
+    echo "Using PUBLIC_TOLGEE_API_URL of $PUBLIC_TOLGEE_API_URL"
+fi
+
+if [[ -z "${PUBLIC_TOLGEE_API_KEY}" ]]; then
+    display_error "PUBLIC_TOLGEE_API_KEY"
+else
+  echo "Using PUBLIC_TOLGEE_API_KEY of $PUBLIC_TOLGEE_API_KEY"
+fi
+
 curl "$PUBLIC_TOLGEE_API_URL/v2/projects/export" -H "X-API-Key: $PUBLIC_TOLGEE_API_KEY" --output translations.zip
 
+if ! curl "$PUBLIC_TOLGEE_API_URL/v2/projects/export" -H "X-API-Key: $PUBLIC_TOLGEE_API_KEY" --output translations.zip; then
+    echo "Failed to download translation zip file? Tried using URL:"
+    echo "$PUBLIC_TOLGEE_API_URL/v2/projects/export"
+    exit 1
+fi
+
 unzip -o translations.zip -d src/i18n/
 
-rm translations.zip
+rm translations.zip
+
+echo "Translation download appears to have succeeded. Be sure to check above for error messages anyways."