Skip to content
Arcane

Contributing to Arcane

Set up the Arcane development environment and submit a pull request.

Run Arcane locally and get your change merged. The dev environment runs the frontend and backend in Docker with hot reload.

Ways to contribute

Section titled “Ways to contribute”
  • Report bugs using the issue template.
  • Suggest features in Discussions. Proposals and voting happen there; maintainers open linked implementation issues when work is ready.
  • Ask development questions in Discussions.
  • Contribute code (frontend, backend, DevOps), documentation, or testing.
  • Translate via Crowdin. See Translating Arcane.

Set up the development environment

Section titled “Set up the development environment”

You need Docker and Docker Compose, plus Vite+ for the Node toolchain, formatting, linting, and pre-commit hooks outside Docker:

Terminal window
curl -fsSL https://vite.plus | bash

Run every command from the project root (arcane/) unless stated otherwise.

  1. Fork and clone the repository, then enter it:
Terminal window
git clone https://github.com/getarcaneapp/arcane.git
Terminal window
cd arcane
  1. Check Docker and the Compose config:
Terminal window
docker info
docker compose version
docker compose -f docker/compose.dev.yaml -p arcane-dev config
  1. Start the development environment:
Terminal window
./scripts/development/dev.sh start

This starts both services with hot reload, installs dependencies inside Docker, and creates persistent storage for dev data.

  1. Confirm the stack is up:
Terminal window
./scripts/development/dev.sh status
curl -f http://localhost:3000
curl -f http://localhost:3552/api/health
  1. Enable the pre-commit hooks once, so format checks run on staged files:
Terminal window
vp hooks enable

Use VS Code (optional)

Section titled “Use VS Code (optional)”

Open the project root (arcane/) and install the recommended Docker, Go, and Svelte/TypeScript extensions. Use Ctrl/Cmd+Shift+P → Tasks: Run Task for Start, Stop, Restart, Rebuild, Logs, and Open Frontend. Ctrl/Cmd+Shift+B starts the environment. The Clean task removes the development containers and volumes, including their data.

Make a change

Section titled “Make a change”

  1. Create a branch:

    Terminal window
    git switch -c feat/project-labels
    git switch -c fix/issue-123

  2. Edit code. Vite reloads the frontend and Air rebuilds and restarts the backend. Watch logs with ./scripts/development/dev.sh logs, or logs frontend / logs backend for one service.

  3. Run the checks before you commit:

Terminal window
vp fmt --check
vp check
docker compose -f docker/compose.dev.yaml exec backend go fmt ./...
docker compose -f docker/compose.dev.yaml exec backend go vet ./...

Frontend formatting and lint rules live in the root vite.config.ts. The backend also runs Go fmt and Go vet as part of Air hot reload.

  1. Commit using Conventional Commits. Types are feat, fix, docs, style, refactor, test, and chore:
Terminal window
git commit -m "feat: add user authentication"
git commit -m "fix: resolve Docker volume mounting issue"

Open a pull request

Section titled “Open a pull request”

Keep each PR to one feature or fix, link issues with Closes #123 or Fixes #456, and respond to review feedback. Update the documentation if you change APIs or add features. Before you submit, check that:

  • The code builds in the development environment
  • Hot reload works for frontend and backend, and both work
  • There are no lint errors
  • Commit messages follow the conventional format
  • The PR description explains the change and why it’s needed

Dev script reference

Section titled “Dev script reference”
Terminal window
./scripts/development/dev.sh start
./scripts/development/dev.sh status
./scripts/development/dev.sh stop
./scripts/development/dev.sh restart
./scripts/development/dev.sh rebuild
./scripts/development/dev.sh logs [frontend|backend]
./scripts/development/dev.sh shell frontend
./scripts/development/dev.sh shell backend

Use restart after config changes and rebuild after dependency changes.

Justfile reference

Section titled “Justfile reference”

just --list shows every target. Common ones:

Task Command
Start the Docker dev environment just dev docker
Follow logs just dev logs
Build the frontend or backend just build single frontend, just build single backend
Run tests just test all, just test backend
Lint and format just lint frontend, just lint js, just format frontend, just format all --check
Install dependencies just deps install all

Run checks inside the Docker dev environment

Section titled “Run checks inside the Docker dev environment”
Terminal window
docker compose -f docker/compose.dev.yaml exec frontend pnpm check
docker compose -f docker/compose.dev.yaml exec frontend pnpm format