Manga XR

The platform to read manga endlessly.
mangaxr.app

Table of contents

• Table of contents
• Running Locally
  • Installation
  • .env files
    • .env.development
    • .env.staging
• Progress list
• Contributing
• License

Running Locally

Installation

• Install Docker if you haven't already.

• Clone the repository:

git clone https://github.com/Friedrich482/manga-xr.git

• Install all necessary dependencies:

npm install

• Generate the Prisma Client for your OS:

npx prisma generate

.env files

.env.development

Create a .env.development file in the root of the directory with the variables DATABASE_URL,SESSION_SECRET, BROWSERLESS_URL and UPLOADTHING_TOKEN.

DATABASE_URL=...
SESSION_SECRET=...
BROWSERLESS_URL=...
UPLOADTHING_TOKEN=...

For the DATABASE_URL, use

DATABASE_URL="mongodb://root:password@localhost:27017/mangaxr-dev?replicaSet=rs0&authSource=admin"

(Local replica set for Prisma transactions, this is a docker volume, so the data will be stored locally)

compose.yaml

For the SESSION_SECRET, you need to generate a SSH Key and get the fingerprint.

ssh-keygen -t rsa -b 4096

Then create an accout on Uploadthing. Then get your keys. For the version 7.7.2, you will need UPLOADTHING_TOKEN

UPLOADTHING_TOKEN=...

At the end the .env.development file should look to something like:

DATABASE_URL="mongodb://root:password@localhost:27017/database?authSource=admin&directConnection=true&replicaSet=rs0"
SESSION_SECRET="SHA256:..."
BROWSERLESS_URL="ws://localhost:3001"
UPLOADTHING_TOKEN=...

Then serve locally:

npm run dev

You also need the compose services for development. There are the browserless-dev service and a Mongo DB replica set, which is a docker volume required for prisma to run the transactions locally. To do so:

make dev-up # to start the services
make dev-down # to stop them

For more information about the commands available, check the Makefile

Prisma Studio to explore and manipulate the data:

npm run dev:studio

Testing GUI with Vitest:

npm run test:ui

.env.staging

The services in the staging compose.yaml allow you to create a staging version on the application with three docker compose services: the app itself, a browserless instance and a MongoDB replica set for Prisma transactions.

Create a .env.staging file in the root of the directory with the variables DATABASE_URL,SESSION_SECRET, BROWSERLESS_URL and UPLOADTHING_TOKEN.

DATABASE_URL=...
SESSION_SECRET=...
BROWSERLESS_URL=...
UPLOADTHING_TOKEN=...

For the DATABASE_URL, use

DATABASE_URL="mongodb://root:password@mongodb-primary:27017/mangaxr_db_staging?replicaSet=rs0&authSource=admin"

For the SESSION_SECRET and UPLOADTHING_TOKEN, you can follow the same steps as in the .env.development And for BROWSERLESS_URL, use:

ws://caddy:3000

(the name of the compose service in the docker network)

You also need a WIREGUARD_PRIVATE_KEY and PROTONVPN_SERVER. Both of them can be obtained by creating a free proton vpn account and generating a wireguard configuration.

At the end, the .env.staging should look to something like:

DATABASE_URL="mongodb://root:password@mongodb-primary:27017/mangaxr_db_staging?replicaSet=rs0&authSource=admin"
SESSION_SECRET="SHA256:..."
BROWSERLESS_URL="ws://caddy:3000"
UPLOADTHING_TOKEN=...
WIREGUARD_PRIVATE_KEY=...
PROTONVPN_SERVER=...
IPCHECK_INTERVAL="0"
PROTONVPN_KILLSWITCH="false"

Then to open the staging version of the application:

make staging-up # to start the services
make staging-down # to stop them

For more information about the commands available, check the Makefile

Prisma Studio to explore and manipulate the data in staging environment:

npm run staging:studio

Progress list

• Change width : responsive width images or adjust the width
• Gap between the page with a range of possible gaps
• Progress Bar (pages read / total of pages)
• One single page or multiple pages
• Next/Prev pages button
• pages drop down
• Chapters dropdown
• Next/Prev chapter Button
• Reading direction (from left to right, from right to left, ...)
• Bookmark the chapter (authentication needed !)
• Add tests with vitest and / or cypress
• Don't forget to add placeholder for lazy loaded images
• Add a type for the cursor class
• Add the manga image in the db to display it in the history
• Create a single or two /lib functions to getUser / getUserId, one with redirect and the oter without it
• create a custom 404 page
• add buttons to reload fetching (for example popular, last released manga) when it fails
• create a separate file for swr tags and revalidateTag tags
• replace "altTitle" by "mangaSlug", which is a more suitable variable name
• BIG task: add history for the mangas with seasons, and also bookmarks support
• also history and bookmark support when the chapters names is not "chapter" but for example "episode"
• add a loading state for the bookmarking
• clear out the search form
• Break the massive zustand store into slices
• use the theme to get system for the theme if it is the case
• When user reaches the end of the last chapter, the next chapter button should lead to the mangaPage instead of being grayed out
• remove all the barrels
• can we use a generic function to represent all cleanup functions ?
• finish the dockerfile and optimize its size
• deploy on google cloud vm (temporary)
• fix the cache issues
• add an open graph image
• fix all tests and add all new tests (for the function sleep and the function clean)
• update the node version in the dockerfile from node 18 to node 20 (minimum)
• update all dependencies, and fix all lint errors
• get uploadthing working in production

Contributing

If you want to contribute:

Fork the repo.

Then clone your fork to your local machine (replace <your_username> by your GitHub username) using:

git clone https://github.com/<your-username>/manga-xr.git

Create a new branch

git checkout -b <new-branch-name>

After making your changes, commit on your branch then submit a Pull Request.

License

MIT License © 2025