#exposing NEXT_PUBLIC_CONVEX_URL and SITE_URL

5 messages · Page 1 of 1 (latest)

heady blade
#

is it safe to expose CLOUD_URL and SITE_URL in public / client side environment variables?

winter dewBOT
#

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

#

It is expected and safe to expose the Convex deployment URL to the client; you just need to be clear on what it does and does not imply.

1. NEXT_PUBLIC_CONVEX_URL (or VITE_CONVEX_URL, etc.)

Convex’s own docs explicitly show and recommend putting your deployment URL in a client‑visible env var like NEXT_PUBLIC_CONVEX_URL / VITE_CONVEX_URL and using it directly in the browser client. [React deployment URL; Next.js module]

Examples:

NEXT_PUBLIC_CONVEX_URL=<https://adjective-animal-123.convex.cloud>

and then:

const convex = new ConvexReactClient(process.env.NEXT_PUBLIC_CONVEX_URL);

This URL is not a secret. It’s just the address of your backend, similar to “https://api.example.com”. Anyone using your app has to be able to reach it. Security comes from:

  • Convex’s auth (Convex Auth, Better Auth, Auth.js, etc.)
  • Database rules encapsulated in your Convex functions
  • Any authentication tokens (JWTs, session cookies) you use

2. SITE_URL and CONVEX_SITE_URL

There are two different “site” URLs in play:

  • Your frontend site URL (often SITE_URL, NEXT_PUBLIC_SITE_URL, etc.) — e.g. <http://localhost:3000> or your Vercel/Netlify URL. This is normally public and is often passed to Convex or Better Auth as a trusted origin or redirect base. [Better Auth Next.js; Better Auth React]
#
  • Convex’s .site URL (CONVEX_SITE_URL or NEXT_PUBLIC_CONVEX_SITE_URL / VITE_CONVEX_SITE_URL) — e.g. <https://adjective-animal-123.convex.site.> This is the public HTTP Actions / auth endpoint for your Convex deployment. Convex docs and examples show using this from the client as well (for Better Auth, Convex Auth, and Auth.js flows). [Better Auth Next.js; NextAuth adapter JWT issuer]

So:

  • Putting SITE_URL (your frontend URL) in a public env var is normal.
  • Putting .site URLs in a public env var (e.g. NEXT_PUBLIC_CONVEX_SITE_URL) is also normal and required for browser‑initiated auth / actions.

3. CONVEX_CLOUD_URL / CONVEX_SITE_URL in Convex functions

Inside Convex itself, there are system env vars:

  • CONVEX_CLOUD_URL — your .cloud URL
  • CONVEX_SITE_URL — your .site URL [System env vars]

These are available to server code (process.env.CONVEX_CLOUD_URL etc.). If you also mirror them to public vars (like NEXT_PUBLIC_CONVEX_URL or NEXT_PUBLIC_CONVEX_SITE_URL), that’s still fine — again, they’re just public endpoints.

4. What you should not expose

The docs only caution about using environment variables for secrets (API keys, private keys, etc.), which must stay on the server / Convex deployment env and not be put into NEXT_PUBLIC_ / VITE_ variables. [Environment variables]

So:

#
  • Safe to expose:
    • NEXT_PUBLIC_CONVEX_URL
    • NEXT_PUBLIC_CONVEX_SITE_URL / VITE_CONVEX_SITE_URL
    • SITE_URL / NEXT_PUBLIC_SITE_URL
  • Not safe to expose:
    • API keys, OAuth client secrets, private keys (e.g. the private key used to sign JWTs for Convex Auth / Auth.js)

If you have a specific variable name/value you’re unsure about, share its purpose (not the secret itself), and I can map it to one of these categories.

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