Nipunn Koorapati

8 months ago

Compiling the Convex Open-Source Backend

Convex recently released an open source version of the backend. We can use this to do local development of an app built on Convex. With local development, you can develop with lower latency, faster push times, and when offline.

We’ll be walking through the process of building from source using the steps from the README. Once you have it compiled, you can check out guides for developing against the local backend or testing against it.

Clone the convex backend repo

git clone https://github.com/get-convex/convex-backend.git

Or if you prefer the GitHub CLI

gh repo clone get-convex/convex-backend

Install Dependencies

Install cargo, rust, just, node, rush, and JS dependencies. Instructions for installation is taken from the README.

# Install rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Install NVM
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

# Open a new shell, and install Convex dependencies
cd convex-backend
cargo install just
nvm use
npm install --prefix scripts
just rush install

Compile and run the Convex backend

just run-local-backend

This command will compile and run the local Convex backend. Note that it may take a while to fully compile depending on how powerful your machine is. You will know it’s ready when you see a log line like this one:

2024-03-20T00:06:44.522791Z  INFO common::http: Listening on http://0.0.0.0:3210

Keep the backend running in the background and open up a new terminal for the next steps.

Developing against the backend

To develop against the backend, you can use the convenience Justfile wrapper command just convex dev.

Note that just convex dev is just a convenience wrapper that specifies the URL and the default admin key.

npx convex 
  --admin-key 0135d8598650f8f5cb0f30c34ec2e2bb62793bc28717c8eb6fb577996d50be5f4281b59181095065c5d0f86a2c31ddbe9b597ec62b47ded69782cd
  --url "http://127.0.0.1:3210"

For more details, check out our post here on developing against the backend

Notes and Limitations

• Compilation of the local-backend can take a long time and turn your computer into a space heater. We’ve had luck with Apple Silicon Mac hardware, but we encourage you to try different setups and let us know how it goes on our Community Discord.
• Upgrading to a newer version of local-backend (via git pull ) may require wiping your local database. You can do this with rm convex_local_backend.sqlite3
• You can run other CLI commands (eg just convex run and just convex env ) just as you would via the cloud development flow.

Related

If you like this, you may also want to check out our other OSS articles

• https://stack.convex.dev/testing-with-local-oss-backend
• https://news.convex.dev/convex-goes-open-source/