search

breadweb / extralife-helper

The Extra Life Helper is a web app that can be used by Extra Life participants and teams to display their fundraising progress. Works in OBS and any modern browser. Features donation alerts, an event countdown timer, a timer for hours played, and multiple themes and display options.
https://breadweb.net/extralife-helper/
MIT License
27 stars 17 forks source link
charity extra-life extralife fundraising livestream obs python react streaming twitch youtubelive

readme

Extra Life Helper

Helper

About

The Extra Life Helper is a web application that Extra Life participants and teams can use to support their fundraising efforts. It was designed to be used in the following ways:


Features

The Helper has been developed and maintained for over a decade. It has a lot of features to help Extra Life participants and teams with their success!


For Extra Life Participants

If you are simply here to use the Helper, please visit the Helper website! It provides a quick and easy way to customize the Helper and generate a link you can use for your LIVE stream or website.

https://breadweb.net/extralife-helper


For Developers

The Extra Life Helper is written in JavaScript and React. Tailwind is used for CSS and Vite is the framework for local development and making builds.

If you've been wanting to develop your own React application that works with the Extra Life API, there are pleny of reusable components and hooks that you can leverage. Also included are some Python scripts that enable rapid local testing against a mock version of the Extra Life API.

If you are interested in modifying the Helper to meet specific requirements for yourself or your Extra Life team, please review the following sections.

Runtime Modes

The Helper runs in one of three different ways:

  1. DEV - This is used when developing the Helper with the Vite development server. Changes you make can be previewed instantly.

  2. LOCAL - This is a compiled version of the Helper that is condensed into a single HTML file. This file can be run in a browser from the file system. It is ideal for personal use of your modified Helper or distribution to a team when you don't have a hosting solution.

  3. REMOTE is used when building the Helper as a collection of files for deployment to a hosting solution such as AWS S3. This is what is used for the official remote version of the Helper but can be used to deploy your modified Helper to your own server.

Development Setup

cd helper
cp .env.local.example .env.local
npm install
npm run dev

The Helper will now be running via the Vite development server at http://localhost:5173.

Configuration

There is a config file per mode. These files contain a combination of application settings and user settings.

User Settings

The Helper is able to be used by anyone by changing the settings. Users will need to provide their participant ID or team ID so the Helper can get their information from the Extra Life API. The remaining user settings affect how the Helper looks and functions.

User settings are parsed differently based on what mode the Helper is running in.

Application Settings

The application settings are highly tuned and not able to be changed by users. The most common use case is developers changing them to support rapid development and testing.

[!CAUTION] Do not change the VITE_POLLING_INTERVAL application setting to a value below 15000 if you are targeting the Extra Life API via the VITE_API_BASE_URL value. A smaller value will almost certainly result in you getting rate limited by the Extra Life API.

Mock API

When developing locally, it is highly reccomended to use the mock API. This will prevent you from accidentally spamming the real Extra Life API and getting rate limited. You will also be able to test different flows by simulating donations.

The mock-api directory contains mock responses for participant and team endpoints currently used by the Helper. Simply run the following command and the mock API will be running http://localhost:5174.

python tools/webserver.py mock-api -p 5174

Then, update the VITE_API_BASE_URL config entry in the .env.local file to this URL value.

The included tools/mock.py Python script provides a number of commands to update the mock API quickly and in the same way the Extra Life API operates. View the help to see the options.

python tools/mock.py -h

Building

To build for LOCAL mode:

cd helper
npm run build:LOCAL

The output will be a single index.html file in the helper/dist directory. The Helper can be run by dragging the file from the file system into a browser.

To build for REMOTE mode:

cd helper
npm run build:REMOTE

The output will be a collection of files in the helper/dist which are intended to be deployed to a hosting solution.

Deployment

Deployment instructions are out of scope for this documentation. If you are considering deploying your modified Helper to your own hosting solution, it is assumed you are familiar with the requirements for deploying a React web application.

Contributing Back

If you have fixed a bug or have a suggested feature change that would benefit all users of the Helper, please make a pull request and I will be happy to review it.

Before creating the PR, please ensure the following:


License

Distributed under the MIT license. See LICENSE for details.


History

I originally created the Helper in 2013. There were no tools available at the time for tracking the time until Extra Life, tracking total time played on game day, and showing fundraising progress. I also wanted to celebrate new donations in real time with my audience while streaming during the marathon. The following year I made it available to the community and it has been used by many Extra Life participants since.


Credits

Translations were provided with help from the following awesome people:


Donations

It's been really rewarding to see the Helper being used by so many people who are supporting a great cause. I do not expect anything in return but if you are determined, you could always make a donation to my Extra Life since this is all for the kids!


Support and Contact

Please report issues here on GitHub. For additional support, you can join my Discord server and post in the #extra-life channel or send me a DM.

I'd also love to see the Helper being used on your stream! Let me know about your channel so I can watch and cheer you on. Good luck in your mission to change kids' health!

Adam "Bread" Slesinger