Convex Setup

Framework Detection

Check package.json dependencies to determine the framework:

• Expo/React Native: Has expo in dependencies → use EXPO_PUBLIC_ prefix for client-side env vars
• Next.js: Has next in dependencies → use NEXT_PUBLIC_ prefix for client-side env vars

Steps

Step 1: Install Dependencies

Check package.json first. Only install what's missing:

npm install convex@latest

If this fails, report the error and stop.

Step 2: Initialize Convex

The Convex credentials must already exist in project secrets before this skill runs:

• URL (EXPO_PUBLIC_CONVEX_URL for Expo or NEXT_PUBLIC_CONVEX_URL for Next.js)
• CONVEX_DEPLOY_KEY

npx convex dev --once

This generates the convex/_generated/ files. Do NOT pass --configure, --team, or --project flags. Do NOT try to log in interactively. If this fails, report the error and stop. NEVER fabricate files inside convex/_generated/ manually.

Step 3: Create the Schema

Create convex/schema.ts with the user's data model. Only define the user's own tables:

import { defineSchema, defineTable } from "convex/server";
import { v } from "convex/values";

export default defineSchema({
  items: defineTable({
    name: v.string(),
    completed: v.boolean(),
    createdAt: v.number(),
  }),
});

Adjust tables and fields based on what the user asked for.

Step 4: Create Query and Mutation Functions

Create Convex functions in the convex/ directory. Example patterns:

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

export const list = query({
  args: {},
  handler: async (ctx) => {
    return ctx.db.query("items").collect();
  },
});

export const create = mutation({
  args: { name: v.string() },
  handler: async (ctx, args) => {
    return ctx.db.insert("items", {
      name: args.name,
      completed: false,
      createdAt: Date.now(),
    });
  },
});

Step 5: Set Up the Provider

Expo: Copy templates/providers/ConvexProvider-expo.tsx to providers/ConvexProvider.tsx. Then wrap the app with <ConvexClientProvider> in app/_layout.tsx or the root component. Make this layout provider change in one edit so tags stay consistent.

Next.js: Copy templates/providers/ConvexProvider-nextjs.tsx to providers/ConvexProvider.tsx. Then wrap the app with <ConvexClientProvider> in app/layout.tsx. Make this layout provider change in one edit so tags stay consistent.

Step 6: Push Schema and Functions

npx convex dev --once

After pushing, use the restart_dev_server tool to restart the dev server so it picks up the new Convex configuration and installed dependencies.

Step 7: Update Existing Components

Replace any local storage usage (AsyncStorage, etc.) with Convex queries/mutations. Use useQuery and useMutation from convex/react:

import { useQuery, useMutation } from "convex/react";
import { api } from "@/convex/_generated/api";

function ItemList() {
  const items = useQuery(api.items.list);
  const createItem = useMutation(api.items.create);

  if (!items) return <Loading />;

  return (
    <>
      {items.map((item) => (
        <ItemRow key={item._id} item={item} />
      ))}
      <Button onPress={() => createItem({ name: "New item" })} />
    </>
  );
}

Required Secrets

The skill requires existing project secrets before running:

• Convex URL under the framework key (EXPO_PUBLIC_CONVEX_URL or NEXT_PUBLIC_CONVEX_URL)
• CONVEX_DEPLOY_KEY

If either is missing, stop and report that setup cannot proceed until both are present.

After Integration

Tell the user: "Convex is connected as your real-time backend."

Do NOT tell users to:

• Edit .env files
• Manually add or configure credentials
• Go to external dashboards