Convex Setup

# Start the Convex development server
npx convex dev

# Generate both keys using the Convex Auth CLI
npx @convex-dev/auth

EXPO_PUBLIC_BACKEND_PROVIDER=convex

npx convex run seed:run

cd apps/app
yarn ios  # or yarn android, yarn web

your-project/
├── convex/                    # Convex backend
│   ├── _generated/           # Auto-generated types (don't edit)
│   ├── auth.ts               # Auth provider configuration
│   ├── schema.ts             # Database schema
│   ├── seed.ts               # Seed data utilities
│   ├── realtime.ts           # Presence & broadcast functions
│   ├── users.ts              # User-related functions
│   ├── storage.ts            # File storage functions
│   ├── crons.ts              # Scheduled jobs
│   └── lib/
│       └── security.ts       # Auth helpers (requireAuth, etc.)
└── apps/app/
    └── app/
        ├── hooks/convex/     # Convex-specific hooks
        ├── providers/        # ConvexProvider setup
        └── services/backend/ # Backend abstraction layer

npx @convex-dev/auth

# List all environment variables
npx convex env list

# Set a variable
npx convex env set VARIABLE_NAME "value"

# Remove a variable
npx convex env unset VARIABLE_NAME

SITE_URL=https://your-project.convex.site

AUTH_GOOGLE_ID=your-client-id
AUTH_GOOGLE_SECRET=your-client-secret

AUTH_APPLE_ID=your-services-id
AUTH_APPLE_SECRET=your-client-secret-jwt

AUTH_GITHUB_ID=your-client-id
AUTH_GITHUB_SECRET=your-client-secret

RESEND_API_KEY=your-resend-api-key
RESEND_FROM_EMAIL=noreply@yourdomain.com
APP_NAME=YourAppName

import { useAuth } from '@/hooks'

function ProfileScreen() {
  const {
    isAuthenticated,
    isLoading,
    user,
    signIn,
    signUp,
    signOut,
    signInWithGoogle,
    signInWithApple,
    signInWithMagicLink,
    verifyOtp,
    updateProfile,
  } = useAuth()

  if (isLoading) return <Loading />

  if (!isAuthenticated) {
    return (
      <View>
        <Button
          onPress={signInWithGoogle}
          title="Sign in with Google"
        />
        <Button
          onPress={signInWithApple}
          title="Sign in with Apple"
        />
      </View>
    )
  }

  return (
    <View>
      <Text>Welcome, {user?.displayName}</Text>
      <Button onPress={signOut} title="Sign Out" />
    </View>
  )
}

import { useQuery } from '@/hooks'
import { api } from '@convex/_generated/api'

function PostList() {
  // Automatically reactive - updates when data changes
  const posts = useQuery(api.posts.list)

  if (posts === undefined) return <Loading />

  return posts.map(post => <PostCard key={post._id} post={post} />)
}

import { useMutation } from '@/hooks'
import { api } from '@convex/_generated/api'

function CreatePost() {
  const createPost = useMutation(api.posts.create)

  const handleSubmit = async () => {
    await createPost({
      title: 'My Post',
      content: 'Hello world!',
    })
  }

  return <Button onPress={handleSubmit} title="Create" />
}

import { requireAuth, requireOwnership } from "./lib/security"

export const updatePost = mutation({
  args: { postId: v.id("posts"), title: v.string() },
  handler: async (ctx, args) => {
    // Throws if not authenticated
    const userId = await requireAuth(ctx)

    // Throws if user doesn't own this post
    await requireOwnership(ctx, "posts", args.postId, userId, "authorId")

    // Safe to update
    await ctx.db.patch(args.postId, { title: args.title })
  },
})

# Populate demo data
npx convex run seed:run

# Check database status
npx convex run seed:status

# Clear all seed data
npx convex run seed:clear

# Add a test user
npx convex run seed:addTestUser

import { useMutation, useQuery } from '@/hooks'
import { api } from '@convex/_generated/api'

function CollaborativeDoc({ docId }) {
  const joinPresence = useMutation(api.realtime.joinPresence)
  const presence = useQuery(api.realtime.getPresence, {
    channel: `doc:${docId}`
  })

  useEffect(() => {
    joinPresence({ channel: `doc:${docId}`, state: { status: 'viewing' } })
    return () => leavePresence({ channel: `doc:${docId}` })
  }, [docId])

  return <Text>{presence?.count} users online</Text>
}

const broadcast = useMutation(api.realtime.broadcast)

// Send cursor position to all users
broadcast({
  channel: `doc:${docId}`,
  event: 'cursor_move',
  payload: { x: 100, y: 200 }
})

import { useMutation } from '@/hooks'
import { api } from '@convex/_generated/api'

function FileUploader() {
  const generateUploadUrl = useMutation(api.storage.generateUploadUrl)
  const saveFile = useMutation(api.storage.saveFile)

  const uploadFile = async (file: File) => {
    // 1. Get upload URL from Convex
    const uploadUrl = await generateUploadUrl()

    // 2. Upload file directly to Convex storage
    const response = await fetch(uploadUrl, {
      method: 'POST',
      headers: { 'Content-Type': file.type },
      body: file,
    })
    const { storageId } = await response.json()

    // 3. Save metadata to database
    await saveFile({
      storageId,
      filename: file.name,
      contentType: file.type,
      size: file.size,
    })
  }

  return <Button onPress={() => pickAndUpload()} title="Upload" />
}

import { useQuery } from '@/hooks'
import { api } from '@convex/_generated/api'

function FileList() {
  const files = useQuery(api.storage.listMyFiles)

  return (
    <FlatList
      data={files}
      renderItem={({ item }) => (
        <View>
          <Text>{item.filename}</Text>
          <Image source={{ uri: item.url }} />
        </View>
      )}
    />
  )
}

// In convex/crons.ts
import { cronJobs } from "convex/server"
import { internal } from "./_generated/api"

const crons = cronJobs()

// Run every hour
crons.interval(
  "my custom job",
  { hours: 1 },
  internal.myModule.myFunction,
  { arg1: "value" }
)

// Run daily at midnight UTC
crons.daily(
  "daily cleanup",
  { hourUTC: 0, minuteUTC: 0 },
  internal.cleanup.runDaily
)

export default crons

// 1. Schema defines types
const schema = defineSchema({
  posts: defineTable({
    title: v.string(),
    views: v.number(),
  }),
})

// 2. Generated types flow through automatically
const posts = useQuery(api.posts.list)
// ^? Post[] | undefined

// 3. TypeScript catches errors at compile time
const createPost = useMutation(api.posts.create)
await createPost({ title: 123 }) // ❌ Error: number not assignable to string
await createPost({ title: "Hello" }) // ✅ Works

npx convex dev  # Runs locally, auto-syncs changes

npx convex deploy  # Deploy to production

npx @convex-dev/auth

yarn start --clear

npx convex dev  # Auto-regenerates _generated/

npx convex dev  # Must be running in a terminal

# Check your SITE_URL
npx convex env list

# Deploy to cloud and set public URL
npx convex deploy
npx convex env set SITE_URL "https://your-project.convex.site"