Skip to content

Commit

Permalink
chore: dev setup process improvements (satisfactorymodding#127)
Browse files Browse the repository at this point in the history 
* chore: add better error messages to download_translations.sh

* chore: setup directions that assume less and cover/avoid common error cases

* chore: improved dev sign in steps
  • Loading branch information
@budak7273
budak7273 authored Nov 7, 2023
1 parent e4591cf commit a2c057c
Show file tree
Hide file tree
Showing 3 changed files with 186 additions and 61 deletions.
175 changes: 152 additions & 23 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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:
Expand Down
45 changes: 8 additions & 37 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -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.
27 changes: 26 additions & 1 deletion download_translations.sh
View file
Original file line number Diff line number Diff line change
@@ -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."

0 comments on commit a2c057c

Please sign in to comment.