DEV Community

Cover image for How to Compile and Run Convex Locally from Source
Fredy Sandoval
Fredy Sandoval

Posted on

How to Compile and Run Convex Locally from Source

#convex #compiling

This guide explains how to build and run the Convex backend from source on
Arch Linux. It is written for developers who are new to the repository and
want a reliable local development setup.

The commands below assume that you are working from the root of the cloned
repository:

cd ~/Documents/OpenSource/convex-backend
Enter fullscreen mode Exit fullscreen mode

What is in this repository?

Convex is an open-source reactive backend and database platform. Applications
define database functions in TypeScript, while the backend provides database
storage, queries, mutations, actions, file storage, scheduled jobs,
authentication, synchronization, search, and related services.

The repository has two main areas:

  • crates/ contains the Rust backend workspace. The local_backend crate produces the convex-local-backend executable.
  • npm-packages/ contains the JavaScript and TypeScript monorepo, managed by pnpm and Turborepo. It includes the Convex client, CLI, dashboards, runtime packages, tests, and demos.

There is also a top-level demo/ directory containing a separate Vite/React
example, plus self-hosted/ documentation for deployment and prebuilt
binary usage.

1. Install Arch Linux system dependencies

Install the compiler toolchain and native libraries required by Rust and the
JavaScript tooling:

sudo pacman -Syu --needed \
  base-devel \
  git \
  curl \
  openssl \
  libsodium \
  rocksdb \
  snappy \
  pkgconf \
  python \
  rustup
Enter fullscreen mode Exit fullscreen mode

base-devel supplies common build tools such as GCC, Make, and Binutils.

You should also have fnm installed. The repository does not require NVM;
fnm is sufficient for managing Node.js versions. On Arch Linux it can be
installed with:

sudo pacman -S --needed fnm
Enter fullscreen mode Exit fullscreen mode

2. Configure fnm and install the required Node.js version

Convex pins Node.js to version 22.22.2 in .nvmrc. Configure fnm for the
current Bash session:

eval "$(fnm env --shell bash)"
fnm install 22.22.2 --use
fnm default 22.22.2
Enter fullscreen mode Exit fullscreen mode

Check that the correct version is active:

node --version
npm --version
Enter fullscreen mode Exit fullscreen mode

The expected Node.js version is:

v22.22.2
Enter fullscreen mode Exit fullscreen mode

To configure fnm automatically for future Bash sessions, add this line to
~/.bashrc:

eval "$(fnm env --use-on-cd --shell bash)"
Enter fullscreen mode Exit fullscreen mode

Then reload Bash:

source ~/.bashrc
Enter fullscreen mode Exit fullscreen mode

If you use Zsh instead, add the equivalent line to ~/.zshrc:

eval "$(fnm env --use-on-cd --shell zsh)"
Enter fullscreen mode Exit fullscreen mode

3. Install the repository-pinned development tools

Convex uses mise to install and manage several exact tool versions,
including Just, CMake, Protocol Buffers, jq, uv, and Rust cargo utilities.

Install mise using its official installer:

curl https://mise.run | sh
Enter fullscreen mode Exit fullscreen mode

Mise will give you instructions on how to add it to your shell for example:

mise: installed successfully to /home/YourUser/.local/bin/mise
mise: run the following to activate mise in your shell:
echo "eval \"\$(/home/YourUser/.local/bin/mise activate zsh)\"" >> "/home/YourUser/.zshrc"
Enter fullscreen mode Exit fullscreen mode

Install the versions declared by mise.toml:

mise install
Enter fullscreen mode Exit fullscreen mode

The repository currently pins these important tools:

Tool Version
Node.js 22.22.2
Rust nightly-2026-06-28
pnpm 10.34.5
Turborepo 2.10.5
Just 1.52.0
CMake 3.31.12
protoc 21.12
uv 0.11.5
jq 1.8.1

Rust automatically uses the toolchain selected by rust-toolchain when you
run commands inside this repository. Verify it with:

rustc --version
cargo --version
Enter fullscreen mode Exit fullscreen mode

If Rust reports that the toolchain is not installed, install it explicitly:

rustup toolchain install nightly-2026-06-28
Enter fullscreen mode Exit fullscreen mode

4. Install the JavaScript tooling

The scripts/ package contains the repository's pinned versions of pnpm,
Turborepo, dprint, and related scripts. Install them with npm:

npm clean-install --prefix scripts
Enter fullscreen mode Exit fullscreen mode

Then install the locked JavaScript workspace dependencies:

just install-js
Enter fullscreen mode Exit fullscreen mode

The lockfile is npm-packages/pnpm-lock.yaml. Keep the lockfile intact and
prefer the repository commands over installing random global versions of
pnpm or Turborepo.

5. Compile the backend from source

The local backend is the Rust binary named convex-local-backend. To compile
it directly in debug mode:

cargo build --locked -p local_backend --bin convex-local-backend
Enter fullscreen mode Exit fullscreen mode

The compiled binary will be under Cargo's target/ directory.

For a release build:

cargo build --release --locked -p local_backend --bin convex-local-backend
Enter fullscreen mode Exit fullscreen mode

The first build can take a long time. Some dependencies include V8 and
Chromium-related source repositories, so Cargo may need to download and
prepare a large dependency graph before Rust compilation begins.

6. Run the backend locally

The recommended development command is:

just run-local-backend
Enter fullscreen mode Exit fullscreen mode

This starts the backend from source and creates the local instance credentials
when necessary.

The default local endpoints are:

Service Address
Convex backend http://127.0.0.1:3210
HTTP Actions proxy http://127.0.0.1:3211

Local state is stored in:

  • convex_local_backend.sqlite3
  • convex_local_storage/

To pass an option to the backend, place it after the Just command, for
example:

just run-local-backend --disable-beacon
Enter fullscreen mode Exit fullscreen mode

To remove local backend state and start over:

just reset-local-backend
Enter fullscreen mode Exit fullscreen mode

Keep the backend terminal running while using the CLI or a demo. Stop it with
Ctrl+C when finished.

7. Build the JavaScript and TypeScript monorepo

Build all workspace packages and their dependencies with Turborepo:

just turbo run build
Enter fullscreen mode Exit fullscreen mode

To build one package and its dependencies, use a filter:

just turbo run build --filter=convex...
Enter fullscreen mode Exit fullscreen mode

The ... means “also build the dependencies of this package.”

For package-level development, for example:

cd npm-packages/convex
npm run build
npm run lint
npm run format-check
npm run typecheck
npm test
Enter fullscreen mode Exit fullscreen mode

Return to the repository root when using the root-level Just commands:

cd ../..
Enter fullscreen mode Exit fullscreen mode

8. Run the included tutorial demo against the local backend

Use two terminals.

In terminal 1, start the backend:

cd ~/Documents/OpenSource/convex-backend
just run-local-backend
Enter fullscreen mode Exit fullscreen mode

In terminal 2, install the JavaScript workspace if you have not already done
so, then start the tutorial's Convex development process:

cd ~/Documents/OpenSource/convex-backend
just install-js
cd npm-packages/demos/tutorial
just convex dev
Enter fullscreen mode Exit fullscreen mode

The repository's just convex helper configures the local backend URL and
uses the generated local admin key.

There is also a separate top-level Vite/React demo. It is not part of the
pnpm workspace, so install its dependencies separately:

cd ~/Documents/OpenSource/convex-backend/demo
npm install
npm run dev
Enter fullscreen mode Exit fullscreen mode

9. Useful development commands

Rust formatting, tests, and linting 

cargo fmt
cargo test
cargo test -p local_backend
cargo clippy
cargo nextest run --no-run --profile ci
Enter fullscreen mode Exit fullscreen mode

JavaScript formatting, tests, and linting 

just turbo run build
cd npm-packages/convex
npm test
npm run lint
npm run format-check
npm run typecheck
npm run test-esm
Enter fullscreen mode Exit fullscreen mode

Local Convex CLI helpers

From the repository root:

just convex dev
just convex data
just convex env
just convex logs
just convex import
just convex export
Enter fullscreen mode Exit fullscreen mode

10. Troubleshooting

node --version shows the wrong version

Reload fnm and select the pinned version:

eval "$(fnm env --shell bash)"
fnm install 22.22.2 --use
Enter fullscreen mode Exit fullscreen mode

just: command not found

Ensure mise is on PATH, then install the repository tools:

export PATH="$HOME/.local/bin:$PATH"
mise install
Enter fullscreen mode Exit fullscreen mode

Cargo cannot download dependencies

The backend has large Git-based dependencies. Confirm that Git and network
access work, then retry:

git --version
cargo build --locked -p local_backend --bin convex-local-backend
Enter fullscreen mode Exit fullscreen mode

JavaScript installation fails with a DNS or registry error

Retry after confirming npm connectivity:

curl -I https://registry.npmjs.org/
npm clean-install --prefix scripts
Enter fullscreen mode Exit fullscreen mode

The demo cannot connect to Convex

Make sure just run-local-backend is still running in another terminal and
that the backend is listening on port 3210:

curl http://127.0.0.1:3210
Enter fullscreen mode Exit fullscreen mode

Start with a completely fresh local backend

This removes only the repository's local backend state:

just reset-local-backend
just run-local-backend
Enter fullscreen mode Exit fullscreen mode

Quick-start summary

Once Arch Linux prerequisites are installed, the normal workflow is:

cd ~/Documents/OpenSource/convex-backend
eval "$(fnm env --shell bash)"
fnm use 22.22.2 --install-if-missing
export PATH="$HOME/.local/bin:$PATH"
mise install
npm clean-install --prefix scripts
just install-js
just run-local-backend
Enter fullscreen mode Exit fullscreen mode

Then use a second terminal for the tutorial demo or JavaScript package
development.

Top comments (0)