Vercel + Supabase Deploy & Verify#

This skill is tuned for a specific personal project (a multi-surface site: marketing + CRM + customer portal, originally עוגנים ישיר / oganimy.co.il), but the patterns generalize. Fork it and swap project name, domain, Supabase project ref, and admin emails. The canonical-bug-fixes sections are the real gold — keep them when adopting.

What This Is (Reference Layout)#

A project at <workspace>/projects/<my-project>/ with:

• Marketing site — /index.html, styles.css, app.js, widget/ (embedded AI chat).
• CRM — /crm/index.html, /crm/crm.js (large vanilla-JS app), staff-only.
• Portal — /portal/index.html, /portal/portal.js, customer-facing.
• Serverless APIs — /api/*.js (Vercel functions; 12-function Hobby plan cap).
• Onboarding wizard — /onboarding/.
• Universal form renderer — /render.html.

Hosted on Vercel, aliased to a custom domain (e.g. https://example.com). DB: a Supabase project ( <your-ref>).

Standard Deploy Workflow#

bash

cd <workspace>/projects/<my-project>

# 1. Edit the file(s).
# 2. Lint-check anything that isn't HTML/CSS:
node -c crm/crm.js portal/portal.js api/<changed>.js

# 3. Bump the version query on every <script>/<link> tag you touched in
#    the relevant index.html (see "Cache busting" below).

# 4. Deploy.
VERCEL_TOKEN=$(cat ~/.openclaw/credentials/vercel/token) \
  npx vercel deploy --prod --yes

# 5. Verify the new code is live.
curl -sL https://example.com/crm/crm.js | grep -c "<marker-from-your-change>"

Deploy usually finishes in 15–25 s. Look for Aliased: https://example.com in the output.

Cache Busting (Critical)#

Vercel's CDN caches crm.js, portal.js, and crm.css aggressively. Use a ?v=YYYYMMDD-<feature> query string on every <script> and <link> to force fresh loads.

html

<!-- crm/index.html -->
<script src="/crm/crm.js?v=20260515-feature"></script>
<!-- portal/index.html -->
<link rel="stylesheet" href="/portal/portal.css?v=20260515-feature">
<script src="/portal/portal.js?v=20260515-feature"></script>

If a widget loads its own CSS from inside its JS, bump that version too:

js

const CSS_HREF = '/widget/chat.css?v=20260515-feature';

Bump the query every time you ship. Forget it once and customers see old JS for up to 24 h, then report bugs that are already fixed.

Supabase Migrations#

Migration SQL files live in deploy/. Apply them with the in-repo runner:

bash

cd <workspace>/projects/<my-project>
node deploy/run-migration.cjs deploy/migration-stageN-<topic>.sql

The runner connects to the Supabase pooler as the postgres superuser using credentials from ~/.openclaw/credentials/supabase/credentials.env.

Always include reset role; at the top of any migration that creates triggers, alters tables, or replaces policies — otherwise the pooler may leave the session as authenticated from a previous transaction and ownership checks fail. See references/migration-template.sql.

For policies on profiles (or any table with a role column): every UPDATE policy MUST have WITH CHECK that locks role and email, or customers can self-promote to admin. See the companion supabase-security-audit skill.

Canonical Bug Fixes#

Modal class convention — .open not .active#

A subtle bug pattern: half the modals use modal.classList.add('open') and work; some use modal.classList.add('active') and silently fail because the CSS only defines .modal.open. Users see "the button does nothing", no JS errors.

Rule: always use 'open' for modal show/hide:

js

modal.classList.add('open');
const close = () => modal.classList.remove('open');

Search for stragglers when touching modal code:

bash

grep -nE "modal\.classList\.(add|remove)\('active'\)" crm/crm.js portal/portal.js
# (must return zero matches)

Profile duplication trap#

A staff-created CRM profile and a Supabase-auth-created profile for the same email produce two rows in public.profiles with different ids. The portal queries by auth.uid(), so the customer sees an empty portal even though their data lives on the other profile id.

The fix: a handle_new_user trigger that merges instead of duplicates. See references/migration-template.sql.

If a customer reports an empty portal despite having data in DB:

sql

select id, email, created_at from profiles where email = '<customer>'
order by created_at;
-- If two rows: the auth-side id (the one in auth.users) is canonical.
-- Merge the other into it (FK repoint + delete orphan).

Magic-link flow#

See the companion magic-link-bridge skill. TL;DR: your api/send-portal-link.js should NOT return the raw Supabase action_link. It should build:

text

https://example.com/portal/?token_hash=<hashed_token>&type=<verification_type>

manually and return that. The portal then handles verifyOtp itself, bypassing the Supabase redirect whitelist (and WhatsApp WebView fragment-dropping bugs).

Floating-action-button stack#

Three floating buttons in the bottom-left, RTL-aware. Stack order (bottom → top):

Elementdesktop bottommobile bottomheight.wa-fab (WhatsApp)28px18px54–60.ogc-fab (AI chat)92px80px54–60.a11y-toggle164px148px50–56

If you add a fourth floating button, place it on top: desktop ~236 px / mobile ~216 px, and bump the corresponding panel as well.

Common file-format gotchas#

• api/_*.js files are ignored by Vercel. Filenames starting with underscore are skipped at deploy time. Use debug-foo.js, not _debug.js.
• Schema column names matter. Audit each table's actual column names before writing UI code. Hidden bugs: querying name when the column is name_he, or title when it's name.
• Storage RLS for documents-like tables needs both: row policy documents.user_id = auth.uid() AND storage policy (storage.foldername(name))[1] = auth.uid()::text. Both must pass.

Verification with Headless Playwright#

When you can't easily reproduce a UI bug, run a Playwright probe. They expect pg and playwright installed under /tmp/<project>-test/:

bash

mkdir -p /tmp/<project>-test && cd /tmp/<project>-test
npm init -y >/dev/null && npm i playwright --no-save
# If your cached chromium version doesn't match the Playwright npm version:
ln -sfn ~/.cache/ms-playwright/chromium_headless_shell-1217 \
        ~/.cache/ms-playwright/chromium_headless_shell-1223 2>/dev/null

Then write a probe (see references/playwright-recipes.md for templates) that:

1. Generates a magic-link via auth/v1/admin/generate_link.
2. Visits https://example.com/portal/?token_hash=<h>&type=magiclink.
3. Inspects the resulting page.

Avoid logging into admin surfaces in automated probes unless necessary — the admin password is a production credential and shouldn't end up in logs.

Vercel Hobby Plan Limits#

• 12 serverless functions cap. Easy to hit. Any new endpoint requires either consolidation (a single api/<area>.js that switches on ?action=...) or moving a feature to Supabase REST directly with the anon key (RLS handles authorization). Endpoints renamed to .deferred are skipped at deploy time and free a slot.

Project Secrets Reference#

• ~/.openclaw/credentials/vercel/token (chmod 600)
• ~/.openclaw/credentials/supabase/credentials.env — SUPABASE_URL, SUPABASE_PROJECT_REF, SUPABASE_ANON_KEY, SUPABASE_SERVICE_ROLE_KEY, SUPABASE_DB_PASSWORD
• ~/.openclaw/credentials/supabase/admin_password.txt — your CRM admin password. Treat as production credential.

See Also#

• supabase-security-audit — run after any RLS or auth change.
• magic-link-bridge — details of the portal redirect bypass.
• services-watchdog — for non-Vercel always-on services in the same workspace.