Development setup

This guide details how to set up Mercury Core for local development and modification.

For a guide on server installation and hosting for production, see Production setup.

Requirements

You should already have the necessary dependencies and command line tools installed. If not, see Installation for an installation guide.

You will need:

Latest version of Git installed (expected as git, optional)
Latest version of Bun installed (expected as bun, installation guide)
Latest version of Go installed (expected as go, installation guide)
Latest version of SurrealDB installed (expected as surreal, installation guide)
A terminal
A modern web browser (Early 2024 onwards for most major browsers)
A computer, as it would be painful to live without one, wouldn't it?

If you wish to use containers instead of SurrealDB and Go, install the latest version of a container manager such as Docker (expected as docker, installation guide) or an alternative container manager like Podman (installation guide).

Instructions

Clone the tp-link-extender/MercuryCore repository to a directory of your choice on your local machine, and navigate to the root directory of the repository.
Terminal window
```
git clone https://github.com/tp-link-extender/MercuryCore
cd MercuryCore
```
- If not using Git, you can also download the repository as a compressed archive file (.zip) from the GitHub page and extract it to a directory of your choice.
If not using containers, navigate to the Economy directory, and run go build to compile the Economy service.
Navigate to the Site directory, and run bun i to install all dependencies.
Copy the Site/.env.example file to Site/.env and modify it to set up the environment variables.
If using containers, run docker compose up -d to start the Database and Economy services.
Run bun dev to start the development server and open the web interface in your default browser. This will start the Database and Economy services automatically if they are not already running.

The development server supports hot reloading, so any changes you make to the code will be automatically reflected in the browser without needing to refresh the page.

After following these steps, you should have a local development server set up for Mercury Core. More information on the development server is available on the Site service page.

Common issues

Filesystem permissions

In some cases, the development server may fail to start due to filesystem permission issues. This can occur if the user running the development server does not have the necessary permissions to read or write to files or directories where dependencies are installed.

An example of potential output could be as follows:

error when starting dev server:
Error: EACCES: permission denied
    at writeFileSync (unknown)
    at write (~/MercuryCore/Site/node_modules/@sveltejs/kit/src/core/sync/utils.js:29:5)
    at write_if_changed (~/MercuryCore/Site/node_modules/@sveltejs/kit/src/core/sync/utils.js:18:3)
    at write_tsconfig (~/MercuryCore/Site/node_modules/@sveltejs/kit/src/core/sync/write_tsconfig.js:47:2)
    at init (~/MercuryCore/Site/node_modules/@sveltejs/kit/src/core/sync/sync.js:17:2)
    at dev (~/MercuryCore/Site/node_modules/@sveltejs/kit/src/exports/vite/dev/index.js:58:7)
    at configureServer (~/MercuryCore/Site/node_modules/@sveltejs/kit/src/exports/vite/index.js:968:17)
    at _createServer (~/MercuryCore/Site/node_modules/vite/dist/node/chunks/node.js:26529:97)
    at async <anonymous> (~/MercuryCore/Site/node_modules/vite/dist/node/cli.js:572:24)
    at processTicksAndRejections (native:7:39)
error: script "dev" exited with code 1

Hot reloading

If you are using WSL2 on Windows, the server may not correctly reflect the changes you make if the repository is stored on the Windows drive. To fix this, move the repository into a folder managed by WSL, or alternatively add the following to the default export of the vite.config.ts configuration file:

server: { watch: { usePolling: true } },