Contributing to Arcane

This page covers running Arcane locally for development and getting a change merged. The dev environment runs the frontend and backend in Docker with hot reload.

Important

Using AI tools? Read the AI Usage Policy before contributing. For project conventions, see AGENTS.md.

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

You need:

• Docker and Docker Compose
• Vite+ for the Node toolchain, formatting, linting, and pre-commit hooks when working outside Docker:

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:

HTTPS

git clone https://github.com/getarcaneapp/arcane.git

SSH

git clone git@github.com:getarcaneapp/arcane.git

GitHub CLI

gh repo clone getarcaneapp/arcane

cd arcane

2. Check Docker and the Compose config:

docker info
docker compose version
docker compose -f docker/compose.dev.yaml -p arcane-dev config

3. Start the development environment:

./scripts/development/dev.sh start

This starts the frontend and backend with hot reload, installs dependencies inside Docker, and creates persistent storage for development data.

4. Confirm the stack is up:

./scripts/development/dev.sh status
curl -f http://localhost:3000
curl -f http://localhost:3552/api/health

• Frontend: http://localhost:3000 (SvelteKit with HMR)
• Backend: http://localhost:3552 (Go with Air hot reload)

5. Enable the pre-commit hooks once, so format checks run on staged files:

vp hooks enable

Use VS Code (optional)

Open the project root folder (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

1. Create a branch:

   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:

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.

4. Commit using Conventional Commits. Types are feat, fix, docs, style, refactor, test, and chore:

git commit -m "feat: add user authentication"
git commit -m "fix: resolve Docker volume mounting issue"

Open a pull request

1. Keep it focused: one feature or fix per PR.
2. Test that both frontend and backend work.
3. Update the documentation if you change APIs or add features.
4. Link issues with Closes #123 or Fixes #456.
5. Respond to review feedback.

Before you submit, check that:

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

Reference

Dev script

./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

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

Checks inside the Docker dev environment

docker compose -f docker/compose.dev.yaml exec frontend pnpm check
docker compose -f docker/compose.dev.yaml exec frontend pnpm format