Thanks for helping make Arcane better! We've built a modern, streamlined development experience that gets you up and running in minutes.
Using AI tools? Please read our AI Usage Policy before contributing.
- 🐛 Report bugs using our issue templates
- 💡 Suggest features or improvements
- 🔧 Code contributions (frontend, backend, DevOps)
- 📚 Documentation improvements
- 🌍 Translations via Crowdin
- 🧪 Testing and quality assurance
- Docker & Docker Compose (that's it! 🎉)
- VS Code based IDE (recommended for the best developer experience)
💡 Working Directory: Unless otherwise specified, all commands in this guide should be run from the project root directory (
arcane/).
git clone https://github.com/<your-username>/arcane.git
cd arcaneFrom the project root directory:
./scripts/development/dev.sh startThat's it! The development environment will automatically:
- 🔥 Start both frontend and backend with hot reload
- 🐳 Handle all dependencies via Docker
- 📊 Set up health checks and monitoring
- 💾 Create persistent storage for your development data
Access your development environment:
- Frontend: http://localhost:3000 (SvelteKit with HMR)
- Backend: http://localhost:3552 (Go with Air hot reload)
For the best development experience, we've included VS Code tasks and workspace configuration.
When you open the project in VS Code, you'll be prompted to install our recommended extensions. These provide:
- Docker integration and management
- Go language support with debugging
- Svelte/TypeScript support
- Integrated terminal management
Use Ctrl/Cmd+Shift+P → "Tasks: Run Task" to access:
| Task | Description |
|---|---|
| Start | Start the development environment |
| Stop | Stop all services |
| Restart | Restart all services |
| Rebuild | Rebuild containers (after dependency changes) |
| Clean | Remove all containers and volumes |
| Logs | Interactive log viewer with service selection |
| Open Frontend | Launch frontend in browser |
Press Ctrl/Cmd+Shift+B to run the default build task (Start Environment).
-
Create a feature branch:
git switch -c feat/my-awesome-feature # or git switch -c fix/issue-123 -
Start development (from project root):
./scripts/development/dev.sh start # or use VS Code Task: "Start" -
Monitor logs (choose your preferred method):
# Interactive selector ./scripts/development/dev.sh logs # Specific service ./scripts/development/dev.sh logs frontend ./scripts/development/dev.sh logs backend # Or use VS Code Task: "Logs"
-
Make your changes - hot reload will automatically update:
- Frontend: Instant HMR via Vite
- Backend: Auto-rebuild and restart via Air
Note: All commands should be run from the project root directory (arcane/).
We provide a Justfile for common workflows. Run just --list to see everything.
# Dev environment
just dev docker
# Tests
just test all
# Linting
just lint frontend
# Formatting
just format frontend# Start development environment
./scripts/development/dev.sh start
# View service status
./scripts/development/dev.sh status
# Stop all services
./scripts/development/dev.sh stop
# Restart services (for config changes)
./scripts/development/dev.sh restart
# Rebuild containers (for dependency changes)
./scripts/development/dev.sh rebuild
# Clean up everything (nuclear option)
./scripts/development/dev.sh clean# Interactive log selection
./scripts/development/dev.sh logs
# All services
./scripts/development/dev.sh logs
# Frontend only (Vite/SvelteKit)
./scripts/development/dev.sh logs frontend
# Backend only (Go/Air)
./scripts/development/dev.sh logs backend
# Shell access
./scripts/development/dev.sh shell frontend
./scripts/development/dev.sh shell backendBoth services include development-time linting and formatting:
- Frontend: ESLint + Prettier (configured in VS Code)
- Backend: Go fmt + Go vet (built into Air hot reload)
If you need to run checks manually:
# Frontend checks
docker compose -f docker/compose.dev.yaml exec frontend pnpm check
docker compose -f docker/compose.dev.yaml exec frontend pnpm format
# Backend checks
docker compose -f docker/compose.dev.yaml exec backend go fmt ./...
docker compose -f docker/compose.dev.yaml exec backend go vet ./...We use Conventional Commits for clear, semantic commit messages:
git commit -m "feat: add user authentication"
git commit -m "fix: resolve Docker volume mounting issue"
git commit -m "docs: update development setup guide"
git commit -m "refactor: simplify API response handling"Types: feat, fix, docs, style, refactor, test, chore
- Keep changes focused - One feature/fix per PR
- Test your changes - Ensure both frontend and backend work
- Update documentation - If you change APIs or add features
- Link issues - Reference issues with "Closes #123" or "Fixes #456"
- Be responsive - Address review feedback promptly
- Code builds successfully in development environment
- Frontend hot reload works correctly
- Backend hot reload works correctly
- No linting errors
- Commit messages follow conventional format
- PR description explains the change and why it's needed
Port conflicts:
# Stop and clean everything (from project root)
./scripts/development/dev.sh clean
# Check for conflicting processes
lsof -i :3000 # Frontend port
lsof -i :3552 # Backend portDocker issues:
# Reset Docker environment (from project root)
./scripts/development/dev.sh clean
docker system prune -f
# Restart development
./scripts/development/dev.sh startVS Code tasks not working:
- Ensure you've opened the project root folder (
arcane/) in VS Code, not a subfolder or parent directory - Install recommended extensions when prompted
- Restart VS Code if tasks don't appear
- Verify you're in the correct working directory when running terminal commands
- Bug Report: Create an issue
- Feature Request: Suggest a feature
- Development Question: Open a discussion in the repository
Thank you for contributing to Arcane! Your help makes this project better for everyone. 🚀