.cursorrules Convex

by @PatrickJS

This document serves as some special instructions when working with Convex.

# Schemas

When designing the schema please see this page on built in System fields and data types available: https://docs.convex.dev/database/types

Here are some specifics that are often mishandled:

## v (https://docs.convex.dev/api/modules/values#v)

The validator builder.

This builder allows you to build validators for Convex values.

Validators can be used in schema definitions and as input validators for Convex functions.

Type declaration
Name	Type
id	(tableName: TableName) => VId<GenericId, "required">
null	() => VNull
number	() => VFloat64
float64	() => VFloat64
bigint	() => VInt64
int64	() => VInt64
boolean	() => VBoolean
string	() => VString
bytes	() => VBytes
literal	(literal: T) => VLiteral
array	(element: T) => VArray
object	(fields: T) => VObject<Expand<{ [Property in string | number | symbol]?: Exclude<Infer, undefined> } & { [Property in string | number | symbol]: Infer }>, T, "required", { [Property in string | number | symbol]: Property | `${Property & string}.${T[Property]["fieldPaths"]}` }[keyof T] & string>
record	(keys: Key, values: Value) => VRecord<Record<Infer, Value["type"]>, Key, Value, "required", string>
union	(...members: T) => VUnion
any	() => VAny
optional	(value: T) => VOptional

## System fields (https://docs.convex.dev/database/types#system-fields)

Every document in Convex has two automatically-generated system fields:

_id: The document ID of the document.
_creationTime: The time this document was created, in milliseconds since the Unix epoch.

You do not need to add indices as these are added automatically.

## Example Schema

This is an example of a well crafted schema.

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

export default defineSchema(
  {
    users: defineTable({
      name: v.string(),
    }),
    
    sessions: defineTable({
      userId: v.id("users"),
      sessionId: v.string(),
    }).index("sessionId", ["sessionId"]),
    
    threads: defineTable({
      uuid: v.string(),
      summary: v.optional(v.string()),
      summarizer: v.optional(v.id("_scheduled_functions")),
    }).index("uuid", ["uuid"]),

    messages: defineTable({
      message: v.string(),
      threadId: v.id("threads"),
      author: v.union(
        v.object({
          role: v.literal("system"),
        }),
        v.object({
          role: v.literal("assistant"),
          context: v.array(v.id("messages")),
          model: v.optional(v.string()),
        }),
        v.object({
          role: v.literal("user"),
          userId: v.id("users"),
        }),
      ),
    })
      .index("threadId", ["threadId"]),
  },
);

General Development Guidelines

Verify Information: Verify before presenting.
No Apologies: Avoid apologies.
No Understanding Feedback: Refrain from feedback about understanding.
No Unnecessary Confirmations: Don’t ask for confirmation of provided information.

Code Modification Practices

File-by-File Changes: Modify files individually.
No Whitespace Suggestions: Avoid whitespace changes.
No Summaries: Don’t summarize changes.
Preserve Existing Code: Maintain existing structures.

Code Quality and Best Practices

Explicit Variable Names: Use descriptive names.
Consistent Coding Style: Follow project style.
Prioritize Performance: Consider performance.
Security-First Approach: Prioritize security.
Modular Design: Encourage modularity.
Avoid Magic Numbers: Use named constants.

Testing and Validation

Test Coverage: Include unit tests.
Error Handling: Implement robust error handling.
Use Assertions: Validate assumptions.

Compatibility and Edge Cases

Version Compatibility: Ensure compatibility.
Edge Cases: Handle potential edge cases.

Documentation and Communication

Real File Links: Provide actual file links.
No Current Implementation: Don’t discuss unless requested.
Check Context File: Verify context file content.

Additional Checks

No Implementation Checks: Don’t verify visible implementations.
No Unnecessary Updates: Avoid unnecessary changes.

Overview of .cursorrules prompt

This set of guidelines provides a comprehensive framework for enhancing code quality and development processes. It emphasizes verifying information, maintaining a consistent coding style, and prioritizing performance and security. The guidelines also focus on robust testing and validation, ensuring version compatibility, and handling edge cases. Additionally, they promote modular design, clear documentation, and efficient communication practices. By following these guidelines, developers can create more maintainable, efficient, and reliable codebases.

Updated: March 14, 2025

This collection of guidelines offers a structured approach to improving code development and maintenance. It covers key areas such as information verification, consistent coding practices, performance optimization, and robust testing. The guidelines also emphasize the importance of modular design, security considerations, and effective documentation. By adhering to these principles, developers can enhance code quality, reduce errors, and improve overall project efficiency.

Usefull for: