Developing with the Open-Source backend
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-backendmay require wiping your local database. You can do this withrm convex_local_backend.sqlite3 - You can run other CLI commands (eg
just convex runandjust 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/
Convex is the sync platform with everything you need to build your full-stack project. Cloud functions, a database, file storage, scheduling, search, and realtime updates fit together seamlessly.