Bright ideas and techniques for building with Convex.
Profile image
Nipunn Koorapati
25 days ago

Developing with the Open-Source backend

Developing with the convex open-source binaries

Convex has 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.

Download the Convex backend binary

Grab the latest binary from this link. You’ll have to pick the appropriate binary for your operating system and CPU architecture. If your architecture isn’t available precompiled, you’ll have to build from source, which we have a guide for here.

Unzip and run the binary from your terminal

./convex-local-backend

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.

Run convex dev

To hit the local OSS backend, convex dev needs to know the url and admin key:

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

Note: This is the default OSS backend admin key. It's ok to check it into source control (and post here 😅).

As a convenience, you can copy the Justfile from the open-source repo into your app:

curl -O https://raw.githubusercontent.com/get-convex/convex-backend/main/Justfile

The Justfile will add the default URL and admin key to all just convex commands. If you don't have just installed, instructions are here - for example cargo install just or brew install just. In my example, I have an app called convex-chess:

cd convex-chess
npm i
just convex dev

Here, we use just convex dev instead of npx convex dev but any command will work, such as just convex env. Note that it is using the version of the Convex CLI specified in the package.json of your project.

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

Run your frontend

Run the appropriate frontend dev command for your application:

next dev

Voila! You’re up and running with local development. Your application will identify the local URL from the .env.local .

Notes and Limitations

  • Upgrading to a newer version of local-backend 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.

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

Build in minutes, scale forever.

Convex is the backend application platform with everything you need to build your project. Cloud functions, a database, file storage, scheduling, search, and realtime updates fit together seamlessly.

Get started