Environment variables
Every setting the theme reads from the environment, what it does, and what breaks if you get it wrong.
Environment variables are the settings that live outside the admin panel — keys,
secrets and connection details. Locally they go in a file called .env.local. On a
host like Vercel you paste them into a form instead.
The theme ships .env.example as a starting point:
cp .env.example .env.local.env.local is in .gitignore and must stay there. It contains secrets. Never
commit it, never paste it into Discord, never put it in a screenshot.
Required
Prop
Type
Optional
Prop
Type
A complete example file
# --- Tebex ---------------------------------------------------------------
TEBEX_TOKEN=your_headless_store_token
SERVER_SECRET=your_game_server_secret
# --- Site ----------------------------------------------------------------
NEXT_PUBLIC_SITE_URL=https://store.example.com
# --- Admin panel ---------------------------------------------------------
PAYLOAD_SECRET=paste_the_64_character_random_string_here
# --- Supabase ------------------------------------------------------------
DATABASE_URI=postgresql://postgres.yourref:yourpassword@aws-0-region.pooler.supabase.com:5432/postgres
SUPABASE_URL=https://yourref.supabase.co
SUPABASE_SERVICE_ROLE_KEY=your_service_role_key
# --- Seed (first run only) ----------------------------------------------
SEED_ADMIN_EMAIL=you@example.com
SEED_ADMIN_PASSWORD=a_password_you_chooseWhere each value comes from: Tebex setup for the first two, Set up Supabase for the Supabase block.
Generating PAYLOAD_SECRET
This signs the cookies that keep you logged in to /admin. If somebody guesses it,
they can forge an admin session on your site. Use a random value, not a word.
openssl rand -hex 32Use a different secret for your live site than for your local copy.
Three secrets that must never be public
TEBEX_TOKEN, SERVER_SECRET and SUPABASE_SERVICE_ROLE_KEY are read on the
server only.
Never rename any of them with a NEXT_PUBLIC_ prefix. Anything named
NEXT_PUBLIC_* is shipped to every visitor's browser. The service role key is the
worst one to leak — it grants full read/write access to your entire Supabase
project.
NEXT_PUBLIC_SITE_URL is the only variable that is meant to be public, and a site
address is not a secret.
Two rules about NEXT_PUBLIC_SITE_URL
- It must exactly match how visitors reach the site.
https://store.example.comis a different origin fromhttps://www.store.example.com. A mismatch makes the basket return403 Cross-origin request rejectedin production. - No trailing slash. Write
https://store.example.com, nothttps://store.example.com/.
Build time vs run time
Some hosts distinguish between variables available while building the site and while running it. Cubed needs these during the build as well:
| Variable | Why the build needs it |
|---|---|
PAYLOAD_SECRET | The build loads the admin panel configuration |
DATABASE_URI | Same |
SUPABASE_URL | The build bakes your Supabase hostname into the image loader and the Content-Security-Policy |
On Vercel, Netlify, Coolify and Dokploy, set every variable in the project's environment settings before the first build — not after.
Missing SUPABASE_URL at build time is a quiet failure: the site deploys, the admin
panel works, uploads succeed — and then your logo is blocked in the browser. If
images are missing after a deploy, check this first.
What breaks when each one is wrong
| Symptom | Almost always this |
|---|---|
| Every store page errors, home page is fine | TEBEX_TOKEN missing or wrong |
Site will not start: PAYLOAD_SECRET must be set in production | PAYLOAD_SECRET missing |
Logged out of /admin after every restart | PAYLOAD_SECRET changes between restarts |
ECONNREFUSED connecting to the database | Using the direct connection string instead of the Session pooler |
| Site starts, every page errors about missing tables | You have not seeded yet — see Install and seed |
Adding to basket returns Cross-origin request rejected | NEXT_PUBLIC_SITE_URL does not match the browser's address |
| Uploaded logo 404s on the live site | Storage bucket is not public, or SUPABASE_URL was missing at build time |
| Uploads rejected in the admin panel | SUPABASE_SERVICE_ROLE_KEY missing or wrong |
| No sale banner during a Tebex sale | SERVER_SECRET missing or wrong |
More detail on all of these in Troubleshooting.