Creating a Convex App with React

In this guide, we'll create a simple Convex app using React. We'll set up a new Convex project, add react-router for navigation, and create a basic UI.

Step 1: Create a New Convex Project

First, we need to create a new Convex project. Open your terminal from your dev folder and run the following command:

bun create convex@latest

This command will prompt you to choose a name for your project and select a template. For this guide, we'll name our project convex-app-1 and choose the React (Vite) template as shown below:

✔ Project name: … convex-app-1
✔ Choose a client: › React (Vite)
✔ Choose user authentication: › none

After that, open the project in your code editor by running:

cd convex-app-1
code .

It looks like a typical react app with some extra folders and files for Convex. Your main concerns are these two folders:

• The convex folder contains your backend code, including your schema and functions.
• The src folder contains your frontend code, where you can create your React components and pages.

Step 2: Initial Setup

Let's run the development server. Presss Ctrl + ~ to open the terminal in your code editor, and run the following command:

bun dev

On the first run, Convex will ask you to create an account and log in. Follow the prompts to set up your account and log in. Once you're logged in, it will ask you a series of questions to set up your project on the Convex platform.

? What would you like to configure? create a new project
? Project name: react-convex
? Use cloud or local dev deployment? cloud deployment

If everything goes well, it will create a new project on the Convex platform and link it to your local project. After that it will run two servers: one for the frontend (your React app) and one for the backend (Convex). It will also open your app in the browser at http://localhost:3000 or a similar port.

Open it in your browser and you should see a welcome page with some instructions on how to get started. You can now start building your app by editing the files in the src folder for the frontend and the convex folder for the backend.

Step 3: Reset

In the src folder, open the App.jsx file and replace the existing code with the following:

export default function App() {
  return <div>hello convex!</div>;
}

Also open index.css and replace the existing code with the following:

@import "tailwindcss";

Our project is CLEAN! We have a blank slate to start building our app.

Step 4 : Add Tanstack Router

We will be creating a whole bunch of mini apps in this project. To keep things organized, we will use Tanstack Router to create different pages for each app. To add Tanstack Router, run the following command in your terminal:

bun add @tanstack/react-router
bun add -D @tanstack/router-plugin

Next, add the highlighted lines to the vite.config.js file to configure the router plugin:

import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import tailwindcss from "@tailwindcss/vite";
import path from "path";
import { tanstackRouter } from "@tanstack/router-plugin/vite";

// https://vite.dev/config/
export default defineConfig({
  plugins: [
    tanstackRouter({
      target: "react",
      autoCodeSplitting: true,
    }),
    react(),
    tailwindcss(),
  ],
  resolve: {
    alias: {
      "@": path.resolve(__dirname, "./src"),
    },
  },
});

Next, create a routes folder in the src directory and create 3 files: __root.jsx, about.jsx, and index.jsx. Some starter code will automatically be generated for you in these files. We will replace the codes later.

TIP

Carefully examine the files generated. It's a plain component but some extra routing related files generated for us, so we don't have to. Each file will correspond to a route in our app. For example, index.jsx will correspond to the / route, about.jsx will correspond to the /about route, and __root.jsx? It will be the wrapper. We will get to that later.

Finally, we change the src/main.jsx file to set up the router. Replace the existing code with the following:

import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import { ConvexProvider, ConvexReactClient } from "convex/react";
import "./index.css";
import { createRouter, RouterProvider } from "@tanstack/react-router";
import { routeTree } from "./routeTree.gen";

// set up a router instance
const router = createRouter({
  routeTree,
  defaultPreload: "intent",
  scrollRestoration: true,
});

// Register for typesafety
declare module "@tanstack/react-router" {
  interface Register {
    router: typeof router;
  }
}

const convex = new ConvexReactClient(import.meta.env.VITE_CONVEX_URL as string);
createRoot(document.getElementById("root")!).render(
  <StrictMode>
    <ConvexProvider client={convex}>
      <RouterProvider router={router} />
    </ConvexProvider>
  </StrictMode>,
);

Now open the app in your browser and you should see the following content:

Hello "__root"!
Hello "/"!

If you do, 🎉 congratulations! You have successfully set up a new Convex project with React and added Tanstack Router for navigation. You can now start building your app by editing the files in the src folder for the frontend and the convex folder for the backend.

Step 5: Creating a nav bar

To create a nav bar, we will edit the __root.jsx file. This file is the wrapper for all our routes, so it's a good place to put our nav bar. Replace the existing code in __root.jsx with the following:

import * as React from "react";
import { Link, Outlet, createRootRoute } from "@tanstack/react-router";
import { Route as IndexRoute } from "./index";
import { Route as AboutRoute } from "./about";

export const Route = createRootRoute({
  component: RootComponent,
});

function RootComponent() {
  return (
    <React.Fragment>
      <nav className="bg-black text-white p-4">
        <Link to={IndexRoute.to}>Home</Link> |
        <Link to={AboutRoute.to}>About</Link>
      </nav>
      <Outlet />
    </React.Fragment>
  );
}

This should be pretty self explanatory. We create a nav bar with two links: Home and About. The Outlet component is where the content of the child routes will be rendered. Now if you open the app in your browser, you should see a nav bar at the top with two links: Home and About. You can click on the links to navigate between the pages.

Conclusion

In this section, we set up a new Convex project with React and added Tanstack Router for navigation. We also created a simple nav bar to navigate between different pages. In the next section, we will start building our first app: the Emoji App! We will learn how to define a schema, write queries and mutations, and connect our frontend to the backend using Convex. Let's get started!