An app for tracking athletes during ultra marathons (Windows, Linux, MacOS)

An Electron application with React and TypeScript.

Configure development environment

1. Install pnpm

   pnpm is used as the package manager. It is a drop-in replacement for 'npm'.

   pnpm website

   # For Windows from the powershell
   iwr https://get.pnpm.io/install.ps1 -useb | iex

2. Install winget (windows only)

   winget is the Microsoft CLI installer

   winget website

   # For Windows from the powershell
   Add-AppxPackage -RegisterByFamilyName -MainPackage Microsoft.DesktopAppInstaller_8wekyb3d8bbwe

3. Install git

   This is a third party product, not from the Github website

   git app website

   # For Windows from the powershell
   winget install --id Git.Git -e --source winget

   # For Linux Ubuntu cli
   sudo apt install git

4. Clone repository

   # For Windows, Linux or MacOS
   git clone https://github.com/barcradio/ultra-tracker

5. Change dir to the new folder (ultra-tracker) that was created in the previous step

   # For Windows, Linux or MacOS
   cd ultra-tracker

6. Install any missing project dependencies

   # For Windows, Linux or MacOS
   pnpm install

7. Rebuild imported packages

   # For Windows, Linux or MacOS
   pnpm rebuild

8. To run a development version of the ultra-tracker app. (This is also called compiling, this is not a build, see Build below)

   # For Windows, Linux or MacOS
   pnpm dev

9. To retrieve the latest changes to your ultra-tracker repository's cloned (remote) version. (Your database and config files will not be changed)

   # For Windows, Linux or MacOS
   # git pull
   # Repeat steps 6 through 7 before running before continuing or performing builds (below)

10. To assist in editing code, logic, or UI, the repository folder can easily be opened with VSCode and the recommended extensions will be installed.

    The VSCode launch settings are configured in the repository to run the app. It runs with a debugger attached by default, but can also be run without, using the launch controls.

    VSCode website

Recommended VSCode IDE Setup

VSCode + ESLint + Prettier + Tailwind CSS IntelliSense

Project structure

In Electron, the app structure is emulated in the src directory. Content in /main is the backend, content in /preload is a small amount of middleware, and content in /renderer is the client frontend.

Consider carefully where the implementation should be located. The implementation on the frontend client that should be at the backend server and can cause synchronization issues and refactoring in the future.

The /shared directory holds common types and global data. This is not an alternative for passing data via IPC.

├───api                             // future server-api
├───main            // backend
│   ├───database                    // only db access
│   ├───ipc                         // ipc to frontend
│   └───lib
├───preload         // middleware
├───renderer        // frontend
│   └───src
│       ├───assets
│       ├───components
│       ├───features
│       │   ├───Footer
│       │   ├───Header
│       │   ├───SettingsHub
│       │   └───Toasts
│       ├───hooks
│       ├───lib
│       └───routes
└───shared                           // common data/types

Build

To build a complete installer for a given environment, use these commands.

  # For windows
  pnpm build:win

  # For macOS
  pnpm build:mac

  # For Linux
  pnpm build:linux

Install

Run the single file executable to install.

# For Windows UI
Double-click the new file created in the previous step

Releasing

To create a new release on GitHub:

1. Update the version in the package.json file

2. Commit the version bump with message e.g. chore(release): bump version to 1.0.0

3. Create a new Git tag with the format vx.x.x This will be applied to the last commit.

   git tag v1.0.0

4. Push the commit and tag to GitHub

   git push v1.0.0

5. The release workflow will fire automatically and create a new release draft on GitHub.

6. After the workflow successfully finishes, edit the release draft, add release notes, and publish the release.

Linting

Linting is the process of running a program that will analyze code for potential errors. The term was derived from the name of the undesirable bits of fiber and fluff.

# View lint errors
pnpm lint

# View lint errors and automatically fix when possible
pnpm lint:fix

Troubleshooting

Issues with better-sqlite-3 functions after the restructure of folders

If the folder structure changes, better-sqlite3 likes to have things rebuilt.

1. Ensure that all code compilation errors are resolved.
2. Run pnpm rebuild before compiling or building