A Tour of Convex
Convex is a novel, fun, and extremely productive way to make backends for your full-stack apps using 100% TypeScript. So let's get an example app up running in a few minutes. Then, we'll explore how it works, improve it together, and along the way learn the fundamentals of how to build your own projects in Convex.
Before you begin: You'll need Node.js 16+ and Git
Ensure you have Node.js version 16 or greater installed on your computer. You
can check your version of Node.js by running node --version
in your terminal.
If you don't have the appropriate version of Node.js installed,
install it from the Node.js website.
In addition, this walkthrough requires Git. If you cannot run the git
command
successfully in your terminal, head over to the
Git website for
instructions.
Your first Convex project in three steps
First, clone the example project repo from GitHub:
git clone https://github.com/get-convex/convex-tour-chat.git
cd convex-tour-chat
In the project root directory, install convex
and the other project
dependencies with npm
:
npm install
Finally, this app's dev
npm command sets up Convex and then runs the web app:
npm run dev
During setup, you'll see that Convex uses your GitHub account for authentication. Sign into Convex with GitHub and then accept the default project setup prompts.
Make sure you keep this command (npm run dev
) running in the background
throughout this tutorial. It's running both the dev web server for the
frontend as well as the convex
command in the background to keep your backend
in sync with your local codebase.
Once your app is up and running, open localhost:5173 and check it out. You'll see a chat frontend running in Node.js on your computer. This frontend connects to your new Convex backend hosted in the cloud, which stores and retrieves the app's chat messages:
Since we just checked this codebase out, you may wonder how it knows to connect
to your specific Convex backend? Information about your project backend was
written to the .env.local
file when we set up the project. When the app starts
up, the Convex client library uses an environment variable to connect to your
backend.
For extra fun, pop up a couple of browser windows and watch Convex relay chat messages between them:
Throughout the rest of this tutorial, we're going to learn more about how this app works and learn about how to build apps in general using Convex. We'll make a few improvements to this app as we go, and finish by integrating some cool GPT AI.
Dive into more projects first?
If instead you want to see other example projects, head on over to our Template Gallery, or see our Quickstarts.
We still recommend you make your way back here eventually to learn the basics about how Convex works and how to "think in Convex." Most developers find that once they master the concepts in this tutorial, they're extremely comfortable making new application architectures on the platform.
Convex main ingredients
In the next three parts, we'll use this chat app to walk through the following fundamental platform concepts:
-
The Convex reactor
First we'll explore the beating heart of Convex, a custom cloud-hosted reactive database called "the reactor." The reactor combines document-relational tables with deterministic TypeScript query and mutation functions. -
Convex and your app
Next, we'll dive into the app's frontend code, and explore how to use Convex client libraries to seamlessly connect your hosted backend to your app. -
The broader platform and the outside world
Finally, we'll touch on the broader backend features outside the reactor that work together to create a comprehensive backend platform. In particular, we'll go deep on actions, Convex's way to create powerful jobs that integrate your app with outside services like OpenAI.
Let's go!