Open source single-machine version of the Convex backend
Convex is the backend-as-a-service for fullstack app development. Thoughtfully curated components, optimized by experts.
Convex replaces your database, server functions, scheduling, storage, vector search, etc. It includes a set of client libraries that deeply integrate with your frontend application code to provide fully consistent caching and real-time updates out of the box. All you need to do is write your application code.
The best way to get started with Convex is to follow the getting started guides in the Convex docs.
Most Convex developers should be using the managed hosted product. The hosted product includes a generous free tier and provides a seamless, reliable, cost-effective platform that allows you to focus on building your application without worrying about infrastructure.
This repository is the wild west open source version. It's the same code used in the hosted Convex product but runs on a single machine and doesn't include the scale-out services, replicated database backend, production dashboard, or operational tooling. You are welcome to use this code to run your application, either for local testing or in production, but you are on your own managing it and ensuring the system is reliable and secure. In particular you should ensure you have strong competency with regards to:
No official support is provided for the open source version of Convex but
community support is available in the #open-source
channel in the
Convex Discord.
Development of the Convex backend is led by the Convex team and we are not actively soliciting any major contributions from the community. We of course welcome bug fixes and love receiving feedback. We keep this repository synced with any internal development work within a handful of days.
We strongly recommend using the hosted version of Convex to get familiar with the development workflow before attempting to run this version locally.
To get started, clone this repo:
git clone https://github.com/get-convex/convex-backend.git
cd convex-backend
You will need to first install the following dependencies if you don't already have them on your machine:
To use the scripts set up in this repo:
Just
Justfile
.cargo install just
or brew install just
To run the Convex CLI:
.nvmrc
nvm use
from the root of the repo.To build the backend from source:
rust-toolchain
rustup
, this will install
automatically.npm install --prefix scripts
just rush install
You can download the latest precompiled binary release from Releases. Only Apple x64, Apple Arm64 (Apple silicon), and Linux x64 binaries are currently available for download.
Note: On MacOS you might need to hold the option
key and double click the
binary file in Finder once, to circumvent the
Gatekeeper warning.
Then you can run it:
./convex-local-backend
Adjust the path based on where you downloaded the binary to or add it to your
PATH
. The backend will store its database in the directory where it is
executed from (not where the binary file lives).
Build and run the local backend from the source in this repo:
just run-local-backend
Under the hood, this builds with Cargo:
cargo run -p local_backend --bin convex-local-backend
This example will go through running the backend with the included demo project.
1. Start the backend
If this fails with an error "persisted db metadata ..." you might need to erase
the local database, in root directory run rm convex_local_backend.sqlite3
.
2. Develop against the backend
The Convex CLI watches for changes in the application source code and pushes the code to backend.
To make the local backend run the included demo project, do:
cd demo
npm i
just convex dev
The convex
script in Justfile
automatically adds appropriate --url
and
--admin-key
flags to point the CLI to the local backend.
To run the client web application you can run the demo Vite server via:
npm run dev:frontend
Note that unlike the hosted Convex workflow, we don't want to run the
dev:backend
command since convex dev
is already running.
The following CLI commands may be useful when interacting with your backend:
just convex data
- Lists tables in your Convex deploymentjust convex env
- Allows you to list/set/update/delete environment variablesjust convex logs
- Streams out log lines to the terminal (it includes all
successful executions if --success
is passed in)just convex import
- Allows you to import tablesjust convex export
- Allows you to export tablesFor full documentation visit docs.convex.dev.
To see how to contribute, visit Contributing.md.
npx convex dev
or just convex dev
before you start testing
your client. The dev
command will take care of updating your .env.local
file with the correct CONVEX_URL
.crates/
contains Rust code
local_backend/
is an application server on top of the Runtime
. This is
the serving edge for the Convex cloud.npm-packages/
contains both our public and internal TypeScript packages.
udf-runtime/
sets up the user-defined functions JS environment for
queries and mutationsudf-tests/
is a collection of functions used in testing the isolate
layersystem-udfs/
contains functions used by the Convex system e.g. the CLIdemo/
contains a demo project that showcases the basic functionality of
Convex using React