# Developing for BeatSaver Reloaded

# Prerequisites

# Repo Layout

The BeatSaver Reloaded repo uses a monorepo format, in that both the client and the server are in the same repository. They are located at /client and /server respectively. Unless otherwise specified, commands to be run for either the client or the server should be run in their directories.

# Data Stores

BeatSaver reloaded uses MongoDB for general data storage and Redis as an ephemeral store for ratelimiting and route caching. Both are required to be running in a development environment.

# MongoDB

MongoDB is a NoSQL data store which is used to store user and beatmap details. The default host for development is localhost:27017, but this can be overriden with environment variables (see Configuration for more info).

If you have Docker installed, you can start a MongoDB instance locally with the following command:

$ docker run --name mongo -p 27017:27017 mongo

# Redis

Redis is an in-memory key-value store which is used to store ratelimit sessions and route caching. The default host for development is localhost:6379, but this can be overriden with environment variables (see Configuration for more info).

WARNING

BeatSaver Reloaded uses database 0 for ratelimit sessions and database 1 for caching. This currently cannot be overriden.

If you have Docker installed, you can start a Redis instance locally with the following command:

$ docker run --name redis -p 6379:6379 redis:alpine

# Elasticsearch

Elasticsearch is a search engine for text and JSON-based documents which is used to power the /search endpoints. The default host for development is localhost:9200, but this can be overriden with environment variables (see Configuration for more info).

WARNING

Elasticsearch is optional for development, but if you wish to disable it, please set ELASTIC_DISABLED=true in your .env file.

Disabling Elasticsearch will return HTTP 501 on all /search endpoints.

If you have Docker installed, you can start an Elasticsearch instance locally with the following command:

$ docker run --name elastic -p 9200:9200 \
  -e "discovery.type=single-node" \
  docker.elastic.co/elasticsearch/elasticsearch:7.1.1

# Configuration

All config for BeatSaver reloaded is done using environment variables. An example .env file has been provided at the root of the repo. To use this in development, copy it into the /server directory and rename it to .env.

WARNING

You must set all required envrionment variables or the server will not start.
An error with the missing variable will be printed to the console.

The example .env file documents everything relevant that you can change. However there are some extra variables that are not meant for general use.

# Override server port
# Not recommended
PORT=3000

# Change environment from dev to prod
# Can be either 'development' or 'production'
NODE_ENV=development

# IDE Tools

BeatSaver Reloaded uses TypeScript for type safety, and TSLint and Prettier for code style enforcement. Having these setup in your IDE of choice will be helpful for development as code is required to adhere to these styles before being merged.

To run code style checks manually:

$ yarn test

It is recommended to use VSCode for development, but you're free to use whatever you like. If you do use VSCode, here is a list of extensions that will be useful:

# Server Setup

First, setup the environment variables. (see Configuration). Next, install dependencies with Yarn.

$ yarn

Yarn scripts have been provided to run everything you need for development. To run the server you need to compile the TypeScript source, then run node. If running the compiler in watch mode you will need two terminals open to run both the compiler and node.

# Start the TypeScript compiler in watch mode
$ yarn dev

# Start node in watch mode
$ yarn dev:run

For a list of all the scripts available, check the server's package.json

# Client Setup

WARNING

Developing for the client requires running the server. It uses localhost:3000 as its base URL for API requests in development mode. Currently this cannot be changed without editing the axios configuration.

First, install dependencies with Yarn.

$ yarn

The client uses Parcel to bundle modules which comes with a development server. You can launch this with a script. By default it runs on port 1234 but if this is in use it will pick a random port and show that in your terminal.

As with the server, yarn scripts have been provided.

$ yarn dev

Parcel leverages a file cache for faster build times. If you wish to clean this cache to ensure a fresh build, a script has been provided to clean the cache and the compiled assets.

$ yarn run clean

# Contributing your code

If you wish to contribute code, first fork the repository. It is recommended to do your work on a feature branch in your fork.

Once you have commited your code, submit a Pull Request. Please fill out the template with all relevant information. Pull requests are subjected to automatic code style checks, so please ensure you adhere to the style guide. Code that does not pass these automatic checks will not be merged.

Code will then be reviewed manually for any bugs or errors. If any are found you will be asked to fix things. If all is well then your code will be merged into the codebase, and you can enjoy a job well done.