Nipunn Koorapati

9 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

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

Or if you prefer the GitHub CLI

1gh repo clone get-convex/convex-backend
2

Install Dependencies

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

1# Install rust
2curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
3
4# Install NVM
5curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
6
7# Open a new shell, and install Convex dependencies
8cd convex-backend
9cargo install just
10nvm use
11npm install --prefix scripts
12just rush install
13

Compile and run the Convex backend

1just run-local-backend
2

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:

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

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.

1npx convex 
2  --admin-key 0135d8598650f8f5cb0f30c34ec2e2bb62793bc28717c8eb6fb577996d50be5f4281b59181095065c5d0f86a2c31ddbe9b597ec62b47ded69782cd
3  --url "http://127.0.0.1:3210"
4

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/