convex-backend

Convex is the open-source reactive database designed tomake life easy for web app developers, whether human or LLM. Fetch data andperform business logic with strong consistency by writing pure TypeScript.

Convex provides a database, a place to write your server functions, and clientlibraries. It makes it easy to build and scale dynamic live-updating apps.Read the docs to learn more.

Development of the Convex backend is led by the Convex team. Wewelcome small bug fixes andlove receiving feedback. We keep this repositorysynced with any internal development work within a handful of days. Convex is awell tested piece of software, with several well designed test frameworksincluding randomized testing. Those tests are not provided as part of the opensource offering.

Getting Started

Visit our documentation to learn more about Convexand follow our getting started guides.

The easiest way to build with Convex is through ourcloud platform, which includes a generous freetier and lets you focus on building your application without worrying aboutinfrastructure. Many small applications and side-projects can operate entirelyon the free tier with zero cost and zero maintenance.

Self Hosting

The self-hosted product includes most features of the cloud product, includingthe dashboard and CLI. Self-hosted Convex works well with a variety of toolsincluding Neon, Fly.io, Vercel, Netlify, RDS, Sqlite, Postgres, and more.

You can either use Docker (recommended) or a prebuilt binary to self hostConvex. Check out our self-hosting guide for detailedinstructions. Community support for self-hosting is available in the#self-hosted channel on Discord.

Community & Support

• Join our Discord community for help anddiscussions.
• Report issues when building and using the open source Convex backend throughGitHub Issues
• By submitting pull requests, you confirm that Convex can use, modify, copy,and redistribute the contribution, under the terms of its choice.

Building from source

See BUILD.md.

Disclaimers

• If you choose to self-host, we recommend following the self-hosting guide. Ifyou are instead building from source, make sure to change your instance secretand admin key from the defaults in the repo.
• Convex is battle tested most thoroughly on Linux and Mac. On Windows, it hasless experience. If you run into issues, please message us onDiscord in the #self-hosted channel.
• Convex self-hosted builds contain a beacon to help Convex improve the product.The information is minimal and anonymous and helpful to Convex, but if youreally want to disable it, you can set the --disable-beacon flag on thebackend binary. The beacon's messages print in the log and only include
  • A random identifier for your deployment (not used elsewhere)
  • Migration version of your database
  • Git rev of the backend
  • Uptime of the backend

Repository layout

• crates/ contains Rust code

  • Main binary
    • local_backend/ is an application server on top of the Runtime. This isthe serving edge for the Convex cloud.

• npm-packages/ contains both our public and internal TypeScript packages.

  • Internal packages
    • udf-runtime/ sets up the user-defined functions JS environment forqueries and mutations
    • system-udfs/ contains functions used by the Convex system e.g. the CLI