Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Developer Setup

Development Containers (Optional)

If you don't want to install another toolchain on your system, You can also use devcontainers instead. If you don't know, think of isolated minimal virtual machines that come with the tools required to build Arcadia (or anything else really).

If you have Docker (recommended!) installed and use Visual Studio Code, all you need is to have the Dev Containers extension installed and "reopening your folder in a container". You can find that option in your Command Palette, or by clicking on the new status bar item in the left bottom corner.

You can also use GitHub Codespaces to build Arcadia in the cloud without having to download anything but streams of text, although it's not as free as a local dev container.

Open in GitHub Codespaces

It isn't required to use them but can be useful in some cases (especially if you're using an immutable OS).

Required Tools

You need these to make meaningful contributions to Arcadia, outside the cases of documentation for example.

  • Prettier for proper formatting of the frontend's code.
  • sqlx-cli for managing database related stuff, including migrations.
  • Docker for setting up dependencies. Optional but HIGHLY recommended!
  • Insomnia for testing the backend's API. You could also use any other client if you want.

Environment Setup

Backend

At runtime, Arcadia's backend will source environment variables to influence it's behavior. The simplest way to set these during development is to write them into a file named .env. A documented sample file is made available, so a quick way to get started is to use it by running cp .env.example .env.

Frontend

At build time, the frontend will be hardcoded with the site's API location sourced from an enviroment variable. A documented sample file is made available, so a quick way to get started is to use it by running cp .env.example .env.

Building and Running

Backend

# Build the backend
cargo build

# Run the backend binary
./target/debug/arcadia

# For optimized builds
cargo build --release
./target/release/arcadia

Frontend

# Install dependencies
npm install

# Build and run development server
npm run dev

# For production build
npm run build

Development Workflow

Backend Development

# For development with auto-rebuild on changes
cargo run

# Build and test
cargo build
cargo test

# Code quality checks
cargo clippy
cargo fmt

Frontend Development

# Development server with hot reload
npm run dev

# Run tests
npm run test:unit

# Lint and format
npm run lint
npm run format