how to have 2 frontend apps point to the same convex app for preview deployment?

[fossil burrow]

how to have 2 frontend apps point to the same convex app for preview deployment? should i use 2 preview keys or the same key? im seeing 502 bad gateway

[cedar quartz]

Hi @fossil burrow. I'm kapa.ai, your friendly support bot. I will try to answer your question by searching through the knowledge base. :wave:

---

You can have multiple frontend apps talk to the same Convex preview deployment, but there are a few gotchas.

1. One preview deploy key is enough

You generally only need one Preview Deploy Key for the project, and you can reuse it across multiple frontend projects. The key just tells npx convex deploy “create/use a preview deployment for this branch,” it doesn’t tie it to a specific frontend. [Deploy key types; Vercel previews]

In practice, people do:

• Run npx convex deploy --cmd '…build…' in one Vercel/Netlify project (or one app in a monorepo). That:
  • Creates the Convex preview deployment
  • Sets the appropriate CONVEX_URL / NEXT_PUBLIC_CONVEX_URL (or similar) for that build. [Vercel previews; React deployment URLs]
• In the other frontend(s), you:
  • Either don’t run npx convex deploy at all and just point them at the same Convex URL via an env var you set yourself, or
  • Also run npx convex deploy, but they’ll still end up pointing at the preview deployment for that branch (as long as they share the same preview key and branch name). [Monorepo thread; Multiple apps on one domain]

A common pattern when pointing multiple Vercel projects at one Convex backend is:

• Only one project runs npx convex deploy.
• The other project(s) are “frontend-only” and just get a CONVEX_SITE_URL / NEXT_PUBLIC_CONVEX_URL env var pointing at that same backend. [Multiple apps summary]

2. Why you might see 502 Bad Gateway

From the sources, the most likely causes are:

• The frontend is pointing at a Convex URL that doesn’t exist (e.g. preview deployment was deleted or never created for that branch). Preview deployments are ephemeral and can be cleaned up automatically. [Preview deployments]
• The second frontend never got the correct CONVEX_URL injected (because npx convex deploy only ran in the other project), so it’s still using a stale or production URL.

To debug:

1. In the Convex dashboard, confirm there is a preview deployment for that branch and copy its .cloud URL.
2. In each frontend preview:
   • Check the env var you use in the client (NEXT_PUBLIC_CONVEX_URL, VITE_CONVEX_URL, etc.) and ensure it matches that URL. [React deployment URLs]
3. If only one project runs npx convex deploy, manually set the Convex URL in the other project’s preview env vars to that same value.

3. Summary recommendation

• Use one Preview Deploy Key for the project.
• Run npx convex deploy in one frontend’s CI to create the preview backend and inject the URL.
• Configure the other frontend(s) to use that same Convex URL via their own environment variables.
• 502s usually mean the second app is pointing at a non-existent or wrong Convex deployment; fix the URL and it should resolve.

---

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

@fossil burrow Kapa.ai is still learning and improving, please let me know how I did by reacting below.

[fossil burrow]

@cedar quartz "Only one project runs npx convex deploy.
The other project(s) are “frontend-only” and just get a CONVEX_SITE_URL / NEXT_PUBLIC_CONVEX_URL env var pointing at that same backend. [Multiple apps summary]" how to make this happen because idk which command will run first

[cedar quartz]

Let me check the knowledge base for you again. One moment! :books:

---

You’re right to worry about “which runs first” — the docs don’t describe any cross‑project orchestration, so you can’t reliably have Convex auto‑wire the URL into one project and then magically reuse it in another. The “one project runs npx convex deploy, others are frontend‑only” pattern is implemented by manually configuring env vars in the other projects, not by ordering builds. [Multiple apps summary]

So the practical setup is:

1. Pick a “backend owner” project

Choose one Vercel/Netlify project (or one app in your monorepo) that:

• Has CONVEX_DEPLOY_KEY (preview key for previews). [Vercel previews; Netlify previews]

• Runs:

  npx convex deploy --cmd 'npm run build'
  

  (plus --preview-run if you seed data). [CLI deploy]

This project is the only one that actually creates/updates Convex deployments.

2. Hard‑wire the Convex URL into the other project(s)

For the other frontend projects:

1. In the Convex dashboard, open the preview deployment (or prod/dev deployment you want to share) and copy its .cloud URL. [React deployment URLs]

2. In each “frontend‑only” project’s environment settings (Vercel/Netlify/etc.), set:

   • NEXT_PUBLIC_CONVEX_URL (or VITE_CONVEX_URL, etc.) to that URL.
   • If you need HTTP actions, also set a *_CONVEX_SITE_URL by replacing .cloud with .site. [System env vars; Discord: site URL from cloud]

3. In code, just read that env var:

   import { ConvexReactClient } from "convex/react";
   
   const convex = new ConvexReactClient(
     process.env.NEXT_PUBLIC_CONVEX_URL as string
   );
   

   [React deployment URLs]

These projects do not run npx convex deploy at all; they just point at whatever Convex deployment you chose.

3. For previews specifically

Convex preview deployments are per branch and auto‑cleaned up. [Preview deployments] There’s no documented way to have Convex automatically push the preview URL from project A into project B’s env vars.

So for true per‑branch preview backends shared by multiple frontends, you currently need some custom glue (e.g. a script or manual copy). The docs and Discord threads don’t describe an official cross‑project automation for that, so anything beyond “manually set the env var to the right URL” would be outside the documented behavior. [Multiple apps summary; Monorepo thread]

In short: the “which command runs first” problem is avoided by not depending on order — only one project runs npx convex deploy, and the others are configured with explicit Convex URLs via their own env vars.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

@fossil burrow Kapa.ai is still learning and improving, please let me know how I did by reacting below.

[fossil burrow]

@cedar quartz this is my 2nd build command, fix it
cd ../../packages/backend && npx convex deploy --cmd 'cd ../../apps/web-v2 && turbo run build' --cmd-url-env-var-name VITE_CONVEX_URL

[cedar quartz]

Let me check the knowledge base for you again. One moment! :books:

---

You don’t want the second app to run npx convex deploy at all if it’s just a frontend pointing at the same Convex preview; that’s what’s causing confusion. The docs and Discord threads show that you typically run npx convex deploy in one place and let the others be “frontend‑only” consumers. [Monorepo deploy; Monorepo with multiple apps]

So instead of “fixing” this as a second convex deploy:

cd ../../packages/backend && \
  npx convex deploy --cmd 'cd ../../apps/web-v2 && turbo run build' \
  --cmd-url-env-var-name VITE_CONVEX_URL

you should:

1. Pick one build (e.g. apps/web) that actually runs:

   cd ../../packages/backend && \
     npx convex deploy --cmd 'cd ../../apps/web && turbo run build' \
     --cmd-url-env-var-name VITE_CONVEX_URL
   

   This is the only place CONVEX_DEPLOY_KEY is used and where the preview Convex deployment is created and VITE_CONVEX_URL is injected. [CLI deploy; Vercel previews]

2. For apps/web‑v2, do not run npx convex deploy. Just build:

   cd ../../apps/web-v2 && turbo run build
   

3. In the hosting provider for web‑v2, set VITE_CONVEX_URL manually to the same Convex URL as the first app (copy from the Convex dashboard or from the first project’s env). [React deployment URLs; Multiple apps]

If you absolutely must run convex deploy from web‑v2 (e.g. separate project that owns the backend), then the command you have is structurally fine; just ensure:

• It’s run from the backend directory (so convex.json is found).
• CONVEX_DEPLOY_KEY is the preview key.
• VITE_CONVEX_URL is what your Vite app actually reads. [CLI deploy; Monorepo turbo example]

But for “two frontends, one Convex preview,” the documented pattern is: one convex deploy, other apps just use the URL via env vars.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

@fossil burrow Kapa.ai is still learning and improving, please let me know how I did by reacting below.

[fossil burrow]

@cedar quartz for preview, is it just "turbo run build" or i need to give the VITE_CONVEX_URL in the cmd?

[cedar quartz]

Let me check the knowledge base for you again. One moment! :books:

---

You don’t pass VITE_CONVEX_URL yourself in the --cmd. npx convex deploy sets it for you.

For previews, the documented pattern is:

npx convex deploy --cmd 'turbo run build'

• npx convex deploy reads the preview CONVEX_DEPLOY_KEY and creates/uses a preview deployment.
• It then sets CONVEX_URL (and the framework‑specific variant like VITE_CONVEX_URL / NEXT_PUBLIC_CONVEX_URL) in the environment for the build command.
• Your turbo run build (Vite/Next/etc.) just reads that env var normally. [CLI deploy; Vercel previews; React deployment URLs]

You only need --cmd-url-env-var-name VITE_CONVEX_URL if Convex can’t infer the right env var name for your setup:

npx convex deploy --cmd 'turbo run build' --cmd-url-env-var-name VITE_CONVEX_URL

---

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon: