Dev workflow

Let's walk through everything that needs to happen from creating a new project to launching your app in production.

This doc assumes you are building an app with Convex and React and you already have a basic React app already up and running. You can follow one of our quickstarts to set this up.

Installing and running Convex

You install Convex adding the npm dependency to your app:

npm i convex

Then you create your Convex project and start backend dev loop:

npx convex dev

The first time you run the npx convex dev command you'll be asked to:

1. Create an account if it doesn't exist
   1. This adds your credentials to your ~/.convex/config.json file. You can run npx convex logout to log your machine out of the account in the future.
2. Create a new Convex project if it doesn't exist

Then Convex will automatically provision a new personal development deployment for this project for you:

1. Deployment details will automatically be added to your .env.local file so future runs of npx convex dev will know what dev deployment to connect to.
2. A convex/ folder will be created (if it doesn't exist), where you'll write your Convex backend functions.

Developing your app

Keep the npx convex dev command running while you're working on your Convex app. This continuously pushes backend code you write in the convex/ folder to your dev deployment. It also keeps the necessary TypeScript types up-to-date as you write your backend code.

You can then add new new server functions to your Convex backend:

convex/tasks.ts

import { query } from "./_generated/server";
import { v } from "convex/values";

// Return the last 100 tasks in a given task list.
export const getTaskList = query({
  args: { taskListId: v.id("taskLists") },
  handler: async (ctx, args) => {
    const tasks = await ctx.db
      .query("tasks")
      .withIndex("taskListId", (q) => q.eq("taskListId", args.taskListId))
      .order("desc")
      .take(100);
    return tasks;
  },
});

When you write and save this code in your editor, several things happen:

1. The npx convex dev command uploads the contents of your convex/ directory to your dev deployment.
2. Your Convex dev deployment analyzes your code and finds all Convex functions. In this example, it determines that tasks.getTaskList is a new public query function.
3. If there are any changes to the schema, the deployment will automatically enforce them.
4. The npx convex dev command updates generated TypeScript code in the convex/_generated directory to provide end to end type safety for your functions.

tip

Check in everything in your convex/_generated/ directory. This it ensures that your code immediately type checks and runs without having to first run npx convex dev. It's particularly useful when non-backend developers are writing frontend code and want to ensure their code type checks against currently deployed backend code.

Once this is done you can use your new server function in your frontend:

src/App.tsx

import { useQuery } from "convex/react";
import { api } from "../convex/_generated/api";

export function App() {
  const data = useQuery(api.tasks.getTaskList);
  return data ?? "Loading...";
}

If you have other configuration like crons or auth in your convex/ folder, Convex ensures that they are applied and enforced on your backend.

Convex dashboard

The Convex dashboard will be a trusty helper throughout your dev, debug and deploy workflow in Convex.

Logs

Since Convex functions are TypeScript functions you can always use the standard console.log and console.time functions to debug your apps.

Logs from your functions show up in your dashboard.

Health, Data, Functions and more

• Health - provides invaluable information on how your app is performing in production, with deep insights on how your Convex queries are doing.
• Data - gives you a complete data browser to spot check your data.
• Functions - gives you stats and run functions to debug them.

There is a lot more to to the dashboard. Be sure to click around or check out the docs.

Deploying your app

So far you've been working on your app against your personal dev deployment for the current project.

All projects have one production deployment. It has separate data and has a separate push process from personal dev deployments, which allows you and your teammates to work on new features using personal dev deployments without disrupting your app running in production.

To push your code to your production deployment for your project you run the deploy command:

npx convex deploy

info

If you're running this command for the first time, it will automatically provision the prod deployment for your project.

Setting up your deployment pipeline

It's rare to run npx convex deploy directly. Most production applications run an automated workflow that runs tests and deploys your backend and frontend together.

You can see detailed deployment and frontend configuration instructions in the Hosting and Deployment doc. For most React meta-frameworks Convex automatically sets the correct environment variable to connect to the production deployment.

Up next

You now know the basics of how Convex works and fits in your app. Go head and explore the docs further to learn more about the specific features you want to use.

Whenever you're ready be sure the read the Best Practices, and then the Zen of Convex once you are ready to "think in Convex."