Using Cursor with Convex
Cursor, the AI code editor, makes it easy to write and maintain apps built with Convex. Let's walk through how to setup Cursor for the best possible results with Convex.
Add Convex to Cursor’s Docs
Cursor composer agent, the main AI coding agent built into Cursor, uses Claude as it's LLM model of choice. While Claude knows about Convex, its knowledge can be patchy or outdated.
We need to give it a helping hand by using the Cursors Docs feature to give it the most up-to-date knowledge of Convex.
From Cursor Settings > Features > Docs add new doc, use the
URL "https://docs.convex.dev/"
Cursor will then index all of the Convex docs for the LLM to use.
You can then reference those docs in your prompt with the @Convex symbol.
You can perform the above steps for https://stack.convex.dev/ too if you would like to provide even more context to the agent.
Install and run Convex yourself
Keeping Convex running is crucial because it automatically generates the client-side types. Without this, the agent can get stuck in a linting loop since it can't access the types for the queries and mutations it created.
We recommended that you install (npm install convex) and run convex
(npx convex dev) yourself in a terminal window.
Use a convex_instructions.md to fine-tune Convex behavior even further
Despite Claude’s inbuilt knowledge of Convex plus referencing @Convex docs the
LLM does still make silly Convex mistakes from time to time. To reduce this even
more create a convex_instructions.md file in /instructions directory. Then
reference it from your prompt.
To get you started see this one we have been using:
Copy the above to your project then reference it in your prompts. You can edit it as needed.
Cursor does have a beta feature called Notepads that may be a better way to do this in the future.
Keep your requests small and git commit frequently
The best results when using agentic LLMs can be found when keeping the amount of changes you want to make small. This lets you be more specific around the context you provide the agent and it means the agent doesn't need to do a lot of searching for context.
After each successful prompt or series of prompts it is a good idea to commit your changes so that its simple to rollback to that point should the next prompt cause issues.
Update and reference your README.md
The agent needs context about the specific business goals for your project. While it can infer some details from the files it reads, this becomes more challenging as your project grows. Providing general information about your project gives the agent a helpful head start.
Rather than including this information in each prompt, it's better to write a comprehensive README.md file in your project root and reference it.
Some people advocate for crafting a Product Requirements Document (PRD), this may be a good idea for more complex projects.