Best practices for Convex, Git and .gitignore
I'm learning how to build a basic website via Vercel, that has simple user inputs that post documents into my Convex DB. As I'm pushing from Dev to Prod via BitBucket, I'm wondering about git best practices after implementing Convex in my project.
For example, to kickstart my project I'm using the Vercel Vite template, which works great. As I now implement Convex into the same project, I'm wondering what to be concerned with regarding what I Convex code I push to git (and bear with me 🐻🤗 I'm new to this!) - in that, when I write Convex Functions they sync to Convex Auto-magically, so should I thus not be capturing these functions via git, as they... serve no purpose in my Dev to Prod website push?
I had a look on Convex regarding git best practices, but couldn't find much info (or at least haven't found anything yet, still looking).
5 Replies
Hey @Karlstens, good question, something we definitely don't have super clearly laid out!
Your dev and prod backends (deployments) can run any code you push to them. They do store your backend code (which you probably have in the convex/ folder), but they don't have a way of sending the code back to you.
So you definitely want to store your code somewhere, so that you can make changes to it and push a new version to your backend. Your computer is the "minimum" storage, but a remote Git repository allows collaboration and backup in case you lose your computer or delete your project folder accidentally.
So if you're using BitBucket (or Github), that's where your remote Git repository is stored.
For what should be included in
.gitignore, besides whatever defaults Vite suggests, we recommend including the .env.local file (in fact the convex CLI will make sure that it's there), because that's where we store the name of your dev backend (from which we infer your Convex team and project). When your future team mate clones your remote repository, they'll have all the backend and frontend code, but they won't have the .env.local file. When they run npx convex dev they'll get a new one configured correctly for the project they choose (if you invite them on the Convex dashboard, they can choose the same project).
This aspect is covered here: https://docs.convex.dev/production/project-configuration
And for hosting on Vercel, you can follow the documentation here: https://docs.convex.dev/production/hosting/vercel
Let us know if you have more questions.Project Configuration | Convex Developer Hub
Local development
Using Convex with Vercel | Convex Developer Hub
Host your frontend on Vercel and your backend on Convex.
Ahh, thanks @Michal Srb - I think I'm now realising the scope of my problem better.
So, my understanding is - there are certain development convex files that should be pushed to the git repository (bitbucket/github) for safe keeping, such as my queries.js functions, so that they can easily be updated and pushed to Convex.
Then there is one file, my .env.local which should only exist in my development environment and not be pushed to the repository.
Further to this, I'm now reading about a ".vercelignore". For example, exploring my live project, I see that the pipeline from BitBucket to Vercel has pushed a README.md file that should only have gone as far as existing in BitBucket and not the Production Site on Vercel.
So that said, I'm creating a file called ".vercelignore" and adding that readme file to it - and it's under this context I'm wondering - what Convex files/folders should persist in BitBucket, but not find their way to my Vercel production site?
EDIT: Such as, I'm wondering if I should add the folder \convex, and its content such as _generated, to my .vercelignore file
EDIT: And also, add the subdirectory \convex_generated to my .gitignore, whilst keeping "\convex" and my custom convex quiries still commiting to git (but not to vercel).
Good question. You're right that Vercel doesn't need the /convex directory for the purposes of running code, because that code runs on Convex, not on Vercel. However, Vercel might need the /convex and /convex/_generated code for the purposes of typechecking and resolving imports like
import { api } from '../convex/_generated/api'. So we recommend giving Vercel all of the /convex code, including _generated.We also recommend checking in Git the convex/_generated folder, because that way typechecking and code browsing (on BitBucket/Github, with "jump to definition") doesn't need project setup. The
_generated folder is tiny, so there's no harm in checking it in.Yah, I noticed it was only 20kb or so - I think last night
Appreciate the help. I'm getting my bearings with all things webdev... last time would have been Geocities, apart from a brief affair with cPanel/