201-convex

Convex Implementation Guide

Setup & Configuration

Convex Project Initialization

1. Install Convex CLI

   pnpm add convex
   pnpm dlx convex dev
   

2. Initialize Convex

   pnpm dlx convex init
   

3. Configure Convex URL
   • Add NEXT_PUBLIC_CONVEX_URL to your .env file.

Directory Structure

• Place Convex schema and functions in /convex/
• Place Convex client config in /lib/convex/
• Place service wrappers in /lib/services/

Implementation Patterns

Convex Schema & Functions

Define your schema and backend logic in /convex/schema.ts and /convex/[module].ts:

// convex/schema.ts
import { defineSchema, v } from "convex/schema";

export default defineSchema({
  visits: {
    path: v.string(),
    userId: v.optional(v.string()),
    metadata: v.any(),
    createdAt: v.number(),
    updatedAt: v.number(),
    indexes: [
      { fields: ["userId", "_creationTime"] },
      { fields: ["path", "_creationTime"] },
      { fields: ["createdAt", "_creationTime"] },
    ],
  },
});

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

export const recordVisit = mutation({
  args: {
    path: v.string(),
    userId: v.optional(v.string()),
    metadata: v.any(),
    createdAt: v.number(),
    updatedAt: v.number(),
  },
  handler: async (ctx, args) => {
    return await ctx.db.insert("visits", args);
  },
});

export const getVisitsByUser = query({
  args: { userId: v.string(), limit: v.optional(v.number()) },
  handler: async (ctx, args) => {
    return await ctx.db
      .query("visits")
      .withIndex("by_user", (q) => q.eq("userId", args.userId))
      .order("desc")
      .take(args.limit ?? 10);
  },
});

Service Layer Pattern

Create service functions to wrap Convex client calls:

// lib/services/visits.ts
import { api } from "@/convex/_generated/api";
import { ConvexReactClient } from "convex/react";

const convex = new ConvexReactClient(process.env.NEXT_PUBLIC_CONVEX_URL!);

export async function recordVisit(args) {
  return convex.mutation(api.visits.recordVisit, args);
}

export async function getVisitsByUser(userId, limit = 10) {
  return convex.query(api.visits.getVisitsByUser, { userId, limit });
}