Skip to main content

React Native Quickstart

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

  1. Create a React Native app

    Create a React Native app using the npx create-expo-app command.

    npx create-expo-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 and its peer dependencies.

    cd my-app && npm install convex react-dom react-native-get-random-values
  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. Install .env helper tool

    To configure your Convex deployment URL via .env files, install react-native-dotenv.

    npm install --dev react-native-dotenv
  5. Configure Babel for .env files

    To use the deployment URL directly from the .env files, configure babel.

    babel.config.js
    presets: ["babel-preset-expo"],
    plugins: ["module:react-native-dotenv"],
  6. 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}
  7. 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
  8. 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".

    convex/getTasks.js
    import { query } from "./_generated/server";

    export default query(async ({ db }) => {
    return await db.query("tasks").collect();
    });
  9. Connect the app to your backend

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

    Import 'react-native-get-random-values' as well.

    App.js
    import { ConvexProvider, ConvexReactClient } from "convex/react";
    import 'react-native-get-random-values';
    import { CONVEX_URL } from "@env";

    const convex = new ConvexReactClient(CONVEX_URL, {
    unsavedChangesWarning: false,
    });

    export default function AppWrapper() {
    return (
    <ConvexProvider client={convex}>
    <App />
  10. Display the data in your app

    Then in the App component use the useQuery hook to fetch from your "getTasks" API.

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

    function App() {
    const tasks = useQuery("getTasks");
    return (
    <View style={styles.container}>
    <Text>{JSON.stringify(tasks, null, 2)}</Text>
  11. Start the app

    Start the app, scan the provided QR code with your phone, and see the serialized list of tasks in the center of the screen.

    npm start

Are you trying to build a universal app targeting both browsers and mobile devices? Use npm create tamagui and apply the steps above to the apps/expo directory and the steps in the Next.js Quickstart to the apps/next directory.