Skip to content

stefanteixeira/magus

Repository files navigation

Magus logo

Magus: a Game Backlog wizard 🧙

Simple app to manage a personal game backlog, inspired by the excellent shelf management from Grouvee and fetching data from IGDB API. Name is inspired by one of the coolest JRPG characters: Magus from Chrono Trigger.

Motivation

Have a lightweight app to manage my game backlog and collection, allowing me to:

  • Keep just the most relevant game information
  • Store data in a local DB, to not rely on external requests and have an easier backup process
  • Easily edit game data, in case it is absent or incomplete on IGDB
  • Fetch how long to beat information from HowLongToBeat
  • Fetch game difficulty information from GameFAQs

Setup

The app is written using Next.js, TypeScript, Tailwind and daisyUI component library. Data is stored in a SQLite database, using Drizzle as an ORM.

Requirements

In order to run it locally, you will need:

  • Node 20 (nvm is recommended to install and manage Node versions)
  • A Twitch Account registered in the Twitch Developer Portal
    • This is required to use IGDB API, further details can be found in their docs here
    • With Twitch Client ID and Client Secret in place, set them as environment variables. Use the .env.local.example to create a .env.local file with your credentials

Running the app

  • Ensure that you have a .env.local file with proper credentials in place
  • Install dependencies: npm install
  • Build the project: npm run build
  • Create the DB: npm run db:schema && npm run db:migrate
  • Start the app:
    • Development mode: npm run dev
    • Production mode: npm run start

App will be available in http://localhost:3000.

Accessing from a Mobile device

The app is responsive enough on Mobile (i.e. not broken, it's decent 😅). You can use ngrok to create a tunnel and access from your phone.

PS: If you are accessing from iOS and is not seeing the background and dark theme, you might have a too old iOS version. I had problems with that on iOS 16.0. Upgrading to the latest (17) fixed it completely.

How it works?

Search

Search a game from IGDB database and add it to your games list. When adding a game to your list, you can:

  • Edit any information (useful when any data is missing from IGDB)
  • Set a star rating
    • Note that half star rating is supported
  • Save the game to a shelf
    • Shelves available: Playing, Played, Wishlist, Backlog and Priority
  • Fetch how long to beat information from HowLongToBeat
    • If it is not available, it will try fetching game length from GameFAQs
  • Fetch game difficulty information from GameFAQs

My Games

Main page from the app, where you can view the list of games and manage your backlog/collection. From this page, multiple actions are possible:

  • Filtering
    • Filter games by Name/Platform/Shelf/Genre
    • Change pagination size (defaults to 30 games per page)
  • Ordering
    • Click on the column header to change the list ordering. Supported in the following columns: Name, Release Date, Finished Date, HLTB, Difficulty and My Rating
  • View game details (clicking on the game name)
  • Set or update a game rating
  • Set or update a game shelf
  • Edit game information
  • Delete a game

Stats

Warning

This page is a work in progress! Currently, it shows a list of covers from games in the Played shelf, filtered by year and supporting ordering by Name or Finished Date.

Add from scratch

It is possible to add a game completely from scratch, without relying on IGDB. This is helpful when a game doesn't exist on IGDB or if it has a lot of missing/incorrect information.

Testing

Tests are located in __tests__ folder in the repository root. For now, there are tests in two levels:

Running tests

To run unit tests:

  • npm run test
  • npm run test:coverage (will save a HTML coverage report inside coverage folder)

To run end-to-end tests:

  • Ensure that you have SQLITE_DB_FILENAME environment variable in your .env.local pointing to the test DB (sqlite_test.db)
  • Install chromium for Playwright: npx playwright install chromium
  • Run tests: npx playwright test

CI

Tests are run on CI with GitHub Actions: ci.yml

TODO

  • Migrate to Next.js App Router
  • Extract Form component
  • Set up charts
  • Set up Visual Regression tests

Support

If this project was helpful for you and you want to support it, you can buy me a coffee at ko-fi 😄☕️

ko-fi

License

License: GPL v3