convex-monorepo Template

To deploy the backend and build the web app simultaneously, run the following command from the root. This command uses Convex to deploy the backend and then triggers the web app build, passing the NEXT_PUBLIC_CONVEX_URL environment variable.

Note: apps/web/vercel.json is pre-configured for this workflow on Vercel.

cd ../../packages/backend && pnpm exec convex deploy --cmd 'cd ../../apps/web && pnpm build' --cmd-url-env-var-name NEXT_PUBLIC_CONVEX_URL

You must create .env.local files in both apps/web and apps/native by copying the provided .example.env files. Ensure the following mappings are correct:

• Convex URL: Copy the CONVEX_URL from packages/backend/.env.local and use it for NEXT_PUBLIC_CONVEX_URL (in apps/web) and EXPO_PUBLIC_CONVEX_URL (in apps/native).
• Clerk Keys:
  • Use your Clerk publishable key in both apps/web/.env.local and apps/native/.env.local.
  • Use your Clerk secret key in apps/web/.env.local only.

Use the --filter flag with pnpm to add dependencies to a specific package within the monorepo.

Examples:

• For the web app: pnpm --filter web-app add <package>@latest
• For the native app: pnpm --filter native-app add <package>@latest
• For the backend: pnpm --filter @packages/backend add <package>@latest

pnpm --filter web-app add mypackage@latest
pnpm --filter native-app add mypackage@latest
pnpm --filter @packages/backend add mypackage@latest

To enable authentication and AI features, add the following to your Convex environment variables:

• Clerk Authentication: CLERK_JWT_ISSUER_DOMAIN=https://your-frontend-api.clerk.accounts.dev
• AI Summaries: OPENAI_API_KEY=...

Follow these steps to set up the development environment for the web and native apps:

1. Install dependencies: Run pnpm install at the root.
2. Configure Convex: Run pnpm --filter @packages/backend setup to log in, create/connect a project, and generate packages/backend/.env.local.
3. Configure Clerk for Convex: Follow the Convex + Clerk guide. Add your Clerk JWT issuer domain to Convex environment variables as CLERK_JWT_ISSUER_DOMAIN.
4. Configure app env files: Create .env.local files in apps/web and apps/native using the .example.env files as templates.
5. Run the apps: Run pnpm dev to start the backend, web app, and native app simultaneously via Turborepo.

If you need to define functions that can read from or modify the database but should not be accessible from the client, use the internal variants. These are only accessible from other Convex functions.

• internalQuery: Accessible only from other Convex functions; can read the database.
• internalMutation: Accessible only from other Convex functions; can modify the database.
• internalAction: Accessible only from other Convex functions; can execute side-effects.

import { internalQuery, internalMutation, internalAction } from "./_generated/server";

export const myInternalQuery = internalQuery({ ... });
export const myInternalMutation = internalMutation({ ... });
export const myInternalAction = internalAction({ ... });

The types in _generated/dataModel.d.ts are automatically generated based on your schema.ts file. If you change your schema, you must regenerate these types to maintain type safety in your backend functions.

Run the following command to regenerate them:

npx convex dev

To trigger a mutation in a React component, use the useMutation hook. This returns a function that you can call to execute the mutation. You can either 'fire and forget' or await the result using .then() or await.

const mutation = useMutation(api.functions.myMutationFunction);

function handleButtonPress() {
  // fire and forget, the most common way to use mutations
  mutation({ first: "Hello!", second: "me" });

  // OR
  // use the result once the mutation has completed
  mutation({ first: "Hello!", second: "me" }).then((result) =>
    console.log(result),
  );
}

To consume a query function in a React component, use the useQuery hook. Pass the function reference from the generated api object and an object containing the required arguments.

const data = useQuery(api.functions.myQueryFunction, {
  first: 10,
  second: "hello",
});

A mutation function is used to modify data in the database (insert, update, or delete). Like queries, mutations use the mutation function from ./_generated/server, require an args schema using v from convex/values, and an async handler. Mutations can also read from the database using ctx.db.

// functions.js
import { mutation } from "./_generated/server";
import { v } from "convex/values";

export const myMutationFunction = mutation({
  // Validators for arguments.
  args: {
    first: v.string(),
    second: v.string(),
  },

  // Function implementation.
  handler: async (ctx, args) => {
    // Insert or modify documents in the database here.
    const message = { body: args.first, author: args.second };
    const id = await ctx.db.insert("messages", message);

    // Optionally, return a value from your mutation.
    return await ctx.db.get(id);
  },
});