Whats the recommended approach for setting up a monorepo with multiple microfrontends using the same convex backend?
lets say I have apps/web1, apps/web2, apps/web3
and internal packages in packages/*
#Recommended Monorepo Setup
daring drift
fresh crestBOT
Hi @daring drift. I'm kapa.ai, your friendly support bot. I will try to answer your question by searching through the knowledge base. :wave:
Recommended Monorepo Setup with Multiple Frontends and a Shared Convex Backend
The recommended approach is to place your Convex backend in a shared internal package (e.g., packages/backend) and have each frontend app depend on it. Here's how it breaks down:
Repository Structure
apps/
├── web1/
├── web2/
└── web3/
packages/
└── backend/
└── convex/ # schema, functions, _generated/
Key Steps
1. Shared Backend Package
Put all your Convex functions, schema, and generated code in packages/backend. Each app imports the generated API from this shared package. [monorepo example]
// Same import in web1, web2, or web3
import { api } from "@workspace/backend/convex/_generated/api";
const contacts = useQuery(api.contacts.list);
const createContact = useMutation(api.contacts.create);
2. Check in Generated Code
Commit the _generated/ directory to version control. This allows all apps to typecheck without needing to run npx convex dev or npx convex codegen first. [best practices]
3. Package Exports
For the packages/backend package, the only export you typically need is from the _generated/api directory. Explicit exports in package.json are not strictly required — path-based imports work equally well — but you can add them if you prefer. [monorepo exports thread]
4. Deploying Multiple Frontend Apps
You can run convex deploy from each app's build command. Since Convex won't redeploy unchanged files, running it from multiple apps is safe. A typical deploy command per app looks like:
cd ../../packages/backend && npx convex deploy --cmd 'cd ../../apps/web1 && turbo run build' --cmd-url-env-var-name NEXT_PUBLIC_CONVEX_URL
You only need to deploy the Convex backend once (from one of the apps); the other apps can just do a frontend-only deploy by setting the CONVEX_SITE_URL environment variable instead of CONVEX_DEPLOY_KEY. [monorepo deploy advice; multiple apps]
5. Package Manager
If you're using a monorepo, pnpm is generally recommended over Bun, as Bun has been known to cause issues (e.g., multiple conflicting copies of the convex dependency being installed). [bun/pnpm advice]