repository·main·Indexed 43 days ago
https://github.com/get-convex/convex-jsA full-stack backend application platform providing a TypeScript/JavaScript SDK, client libraries, and CLI for building real-time, scalable applications. Version 1.46.0 includes tools for defining database schemas with defineSchema and defineTable, creating reactive queries, transactional mutations, and side-effect actions, as well as managing file storage, cron jobs, and authentication.
The npx convex ai-files remove command does not rely on local tracking of installed skill names or their provenance. Instead, it uses the canonical version catalog as the single source of truth.
When you run remove:
https://version.convex.dev/v1/agent_skills.convex/_generated/ai/ai-files.state.json (specifically the installedSkillNames field).This ensures that removal is driven entirely by the remote service, allowing for cleaner management of skills even if they were manually installed or if local state files are corrupted/outdated.
The Convex server-side code follows an "interface-impl" pattern to balance developer type safety with internal implementation simplicity:
DataModel type. This ensures that when you use these abstractions in your queries and mutations, you are guided by strict type safety based on your specific schema.impl/ subdirectory): The impl/ directory contains the actual logic. These implementations are not parameterized over DataModel. They use looser typing to simplify internal development, as the primary goal of the DataModel type is to assist the end-user in writing correct code rather than validating the internal library structures.The convex package is modular, providing specific entry points depending on your application layer:
convex/server to define backend functions and database schemas.convex/react for hooks and the ConvexReactClient.convex/browser for the ConvexHttpClient in non-React browser environments.convex/values for utilities related to values stored in Convex.convex/react-auth0 (Auth0) and convex/react-clerk (Clerk).convex/nextjs for server-side helpers compatible with Next.js and other React frameworks.convex command-line interface is used for managing Convex projects.Convex functions are categorized into three types:
Use queryGeneric, mutationGeneric, and actionGeneric (or their shorthand query, mutation, and action exports in your environment) to define these functions.
import { query, mutation, action } from "convex/server";
export const myQuery = query({
args: { name: v.string() },
handler: async (ctx, args) => {
return await ctx.db.query("users").filter(q => q.eq(q.field("name"), args.name)).collect();
},
});
export const myMutation = mutation({
args: { name: v.string() },
handler: async (ctx, args) => {
await ctx.db.insert("users", { name: args.name });
},
});Convex uses a schema definition to provide type safety for your database. Use defineSchema to wrap your table definitions and defineTable to define the structure of individual tables. You can also define indexes and search indexes directly within the TableDefinition.
import { defineSchema, defineTable } from "convex/server";
export default defineSchema({
users: defineTable({
name: v.string(),
email: v.string(),
}).index("by_email", ["email"]),
posts: defineTable({
authorId: v.id("users"),
title: v.string(),
body: v.string(),
}).searchIndex("search_body", {
searchField: "body",
filterFields: ["authorId"],
}),
});When running npx convex ai-files install or npx convex ai-files update, the CLI writes skills to agent-native locations. Depending on your configuration, verify the following paths:
.agents/skills/: The canonical project-scoped installation path..claude/skills/: Symlinks for Claude Code when claude-code is configured.aiFiles.skills.agents.Note: .cursor/skills/ is not a default installation path. The default agents are codex and claude-code.
You can check the current list of installed skills by running npx convex ai-files status after installation.
When testing unreleased changes or working with a local stub of the version service, you can point the Convex CLI to a local endpoint using the CONVEX_VERSION_API_ORIGIN environment variable. This is particularly useful during rollout windows when the local CLI expects a newer response shape from the /v1/agent_skills endpoint than the deployed service currently provides.
CONVEX_VERSION_API_ORIGIN=http://127.0.0.1:3212 npx convex ai-files removeWhen using a preview deploy key (via CONVEX_DEPLOY_KEY), you can manage preview deployments using these flags:
--preview-name <name>: Associates the deployment with a specific name. In CI environments (Vercel, Netlify, Cloudflare Pages, GitHub), this defaults to the current Git branch name. If a deployment with that name already exists, it reuses it.--preview-create <name>: Similar to --preview-name, but it deletes and recreates an existing preview deployment with the same name. This can only be used with a preview deploy key.Note: These two flags conflict and cannot be used together.
npx convex deploy --preview-name my-feature-branch
# Or to force a recreation:
npx convex deploy --preview-create my-feature-branchUse the npx convex deploy command to push your Convex functions, indexes, and schema to a deployment. This command is intended for manual deployments or CI/CD pipelines. For local development, use npx convex dev instead.
The target deployment is determined automatically based on your environment variables:
CONVEX_DEPLOYMENT_ENV_VAR_NAME is set, it targets the project's default production deployment.CONVEX_DEPLOY_KEY_ENV_VAR_NAME is set (typical in CI), it targets the deployment associated with that key. If the key is a preview deploy key, it targets a preview deployment.When you run deploy, the CLI performs the following steps in order:
--cmd is provided, it runs that command with the deployment URL available as an environment variable.convex/_generated directory.--preview-run is specified, it executes that function.npx convex deployThe Convex CLI requires a minimum Node.js version to function correctly.
Requirements:
If your current Node version is below this requirement, the CLI will exit with an error. It is recommended to use nvm (Node Version Manager) to manage and update your Node.js versions.
The configure command (used internally by npx convex dev and npx convex init) allows you to set up or switch between Convex projects. You can create a new project or link to an existing one. The configuration process manages environment variables like CONVEX_DEPLOYMENT and CONVEX_URL, and ensures your local environment is correctly pointed to the intended deployment (cloud dev, cloud prod, or local).
npx convex configure