Convex Actions and General Guidelines Skill

This skill provides comprehensive guidance for Convex actions, HTTP endpoints, validators, schema design, file storage, environment variables, scheduling, and TypeScript best practices.

When to Use This Skill

Use this skill when:

Implementing action functions for external API calls and long-running tasks
Creating HTTP endpoints for webhooks or public APIs
Defining validators for function arguments and database schemas
Designing database schemas with tables, indexes, and search capabilities
Setting up environment variables for secrets and configuration
Implementing cron jobs and scheduled tasks
Working with file storage for uploads and downloads
Using Convex-specific TypeScript patterns and types
Understanding Convex limits and performance constraints

Skill Resources

This skill includes comprehensive reference documentation in

references/actions-and-general.md

that covers:

Actions and HTTP

Actions: Defining actions with
```
"use node"
```
for Node.js modules
- V8 vs Node runtime differences
- Action limitations (10-minute timeout, no database access)
- Calling external APIs and services
HTTP Endpoints: Setting up
```
convex/http.ts
```
with httpRouter
- Path registration and exact matching
- Request/response handling
- Method definitions (POST, GET, etc.)

Validators and Types

Complete validator reference for all Convex types

Common validators:

v.object()

v.array()

v.string()

v.number()

v.id()

v.boolean()

v.null()

Discriminated union types with
```
v.union()
```
and
```
v.literal()
```
ASCII field name requirements for objects
Size and element count limits

Function Development

New function syntax for all function types

Function registration patterns (

query

mutation

action

internalQuery

internalMutation

internalAction

)

Function calling patterns across runtimes
Function references via
```
api
```
and
```
internal
```
objects
File-based routing conventions

API Design

Organizing public and private functions
Thoughtful file structure within
```
convex/
```
directory
Public vs. internal function visibility
API surface consistency

Database and Schema

Schema Definition:
```
convex/schema.ts
```
structure
- System fields (
```
_id
```
  ,
```
_creationTime
```
  )
- Table definitions with validators
Indexes: Creating efficient indexes
- Built-in indexes (by_id, by_creation_time)
- Custom index naming and field ordering
- Multiple field indexes for complex queries
Full Text Search: Search index definitions
- Search fields and filter fields
- Nested field paths with dot notation

Environment and Configuration

Environment Variables: Using
```
process.env
```
- Storing secrets (API keys, credentials)
- Per-deployment configuration
- Access from any function type
Scheduling:
- Crons: Using
```
crons.interval()
```
  and
```
crons.cron()
```
- Scheduler: Using
```
ctx.scheduler.runAfter()
```
  from mutations/actions
- Auth state propagation (doesn't propagate to scheduled jobs)
- Timing constraints and best practices

File Storage

Upload URL generation with
```
ctx.storage.generateUploadUrl()
```
Signed URL retrieval with
```
ctx.storage.getUrl()
```
File metadata from
```
_storage
```
system table
Blob conversion for storage operations
Complete example: image upload in chat application

Limits and Performance

Function arguments and return values: 8 MiB maximum
Database operations: 8192 document writes per mutation, 16384 reads per query
Execution timeouts: 1 second for queries/mutations, 10 minutes for actions
Array element limits: 8192 maximum
Object/Record field limits: 1024 maximum
Nesting depth: 16 maximum
Record size: 1 MiB maximum
HTTP streaming: 20 MiB maximum output

TypeScript

```
Id<'tableName'>
```
types for strict document IDs
```
Doc<'tableName'>
```
types for document type safety
```
Record<KeyType, ValueType>
```
with proper typing
```
as const
```
for discriminated unions
Type annotations for same-file function calls
```
@types/node
```
for Node.js modules

How to Use This Skill

Read the reference documentation at
```
references/actions-and-general.md
```
for comprehensive patterns
Follow the syntax for defining actions with proper Node.js module handling
Use validators correctly for all function arguments and schema fields
Design schemas with appropriate indexes for your access patterns
Set up environment variables for secrets and configuration
Implement scheduling for background tasks using crons or the scheduler
Handle file storage with proper URL generation and metadata lookup
Understand limits and design applications to respect them
Use TypeScript strictly with
```
Id
```
types and proper generics

Key General Guidelines

ALWAYS use argument validators for all functions (queries, mutations, actions)
Do NOT store file URLs in the database; store file IDs instead
Remapping non-ASCII characters (emoji) to ASCII codes before storing in objects
Auth state does NOT propagate to scheduled jobs; use internal functions
Scheduled functions should not run more than once every 10 seconds
Never call actions from other actions unless crossing runtimes (V8 to Node)
Objects in Convex must have ASCII-only field names
Be strict with TypeScript types, especially for document IDs

Example: Complete Action with HTTP Endpoint

// convex/ai.ts
"use node";
import { action } from "./_generated/server";
import { v } from "convex/values";
import { internal } from "./_generated/api";
import OpenAI from "openai";

const openai = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
});

export const generateResponse = action({
  args: {
    channelId: v.id("channels"),
  },
  handler: async (ctx, args) => {
    // Actions can't access ctx.db, but can call mutations
    const context = await ctx.runQuery(internal.functions.loadContext, {
      channelId: args.channelId,
    });

    const response = await openai.chat.completions.create({
      model: "gpt-4o-mini",
      messages: context,
    });

    const content = response.choices[0].message.content;
    if (!content) throw new Error("No content in response");

    await ctx.runMutation(internal.functions.writeAgentResponse, {
      channelId: args.channelId,
      content,
    });

    return null;
  },
});

Example: HTTP Endpoint

// convex/http.ts
import { httpRouter } from "convex/server";
import { httpAction } from "./_generated/server";

const http = httpRouter();

http.route({
  path: "/webhook",
  method: "POST",
  handler: httpAction(async (ctx, req) => {
    const body = await req.json();
    // Process webhook payload
    return new Response(JSON.stringify({ success: true }), { status: 200 });
  }),
});

export default http;

For more detailed information and additional patterns, refer to the complete reference documentation.

convex-actions-general

NPX Install

Tags

SKILL.md Content