React Quickstart

Learn how to query data from Convex in a React app.

1. Create a React app

   Create a React app using the create-react-app command.

   npx create-react-app my-app
2. Install the Convex client and server library

   To get started, install the convex package which provides a convenient interface for working with Convex from a React app.

   Navigate to your app and install convex.

   cd my-app && npm install convex
3. Setup a Convex dev deployment

   Next, run npx convex dev. This will prompt you to log in with GitHub, create a project, and save your production and deployment URLs.

   It will also create a convex/ folder for you to write your backend API functions in. The dev command will then continue running to sync your functions with your dev deployment in the cloud.

   npx convex dev
4. Create sample data for your database

   In a new terminal window, create a sampleData.jsonl file with some sample data.

   sampleData.jsonl

   {"text": "Buy groceries", "isCompleted": true}
   {"text": "Go for a swim", "isCompleted": true}
   {"text": "Integrate Convex", "isCompleted": false}
5. Add the sample data to your database

   Now that your project is ready, add a tasks table with the sample data into your Convex database with the import command.

   npx convex import tasks sampleData.jsonl
6. Expose a database query

   Add a new file getTasks.js in the convex/ folder with a query function that loads the data.

   The default export declares an API function named after the file, "getTasks".

   src/convex/getTasks.js

   import { query } from "./_generated/server";
   
   export default query(async ({ db }) => {
     return await db.query("tasks").collect();
   });
7. Connect the app to your backend

   In index.js, create a ConvexReactClient and pass it to a ConvexProvider wrapping your app.

   src/index.js

   import { ConvexProvider, ConvexReactClient } from "convex/react";
   
   const convex = new ConvexReactClient(process.env.REACT_APP_CONVEX_URL);
   root.render(
     <React.StrictMode>
       <ConvexProvider client={convex}>
         <App />
8. Display the data in your app

   In App.js, use the useQuery hook to fetch from your "getTasks" API function.

   src/App.js

   import { useQuery } from "./convex/_generated/react";
   
   function App() {
     const tasks = useQuery("getTasks");
     return (
       <div className="App">
         {JSON.stringify(tasks, null, 2)}
9. Start the app

   Start the app, go to http://localhost:3000 in a browser, and see the serialized list of tasks at the top of the page.

   npm start