Option 1: Vercel Cron calling a Route Handler

You add a crons entry to vercel.json, and Vercel sends a GET request to a path in your app on that schedule:

{
  "crons": [
    { "path": "/api/cron/cleanup", "schedule": "0 3 * * *" }
  ]
}

// app/api/cron/cleanup/route.ts
import { createClient } from "@supabase/supabase-js";

export async function GET(request: Request) {
  if (request.headers.get("authorization") !== `Bearer ${process.env.CRON_SECRET}`) {
    return new Response("Unauthorized", { status: 401 });
  }
  const supabase = createClient(
    process.env.NEXT_PUBLIC_SUPABASE_URL!,
    process.env.SUPABASE_SERVICE_ROLE_KEY!
  );
  const { error } = await supabase
    .from("sessions")
    .delete()
    .lt("expires_at", new Date().toISOString());
  if (error) return new Response(error.message, { status: 500 });
  return Response.json({ ok: true });
}

Good for: jobs that reuse your app code, call third-party APIs with secrets you already keep in Vercel, or render emails with the same templates as your UI.

Watch out for:

• Schedules are in UTC, and cron jobs only run on production deployments, not previews.
• How often a job can run, and how precisely it is timed, depends on your Vercel plan. Check the current limits before you design around "every 5 minutes".
• The route is a public URL. Set CRON_SECRET in your project's environment variables and check the Authorization header as above, or anyone can trigger the job.
• The job is a normal serverless function, so it has the same maximum duration. Batch the work instead of looping over every row in one request.

Option 2: pg_cron inside Supabase

If the job is pure SQL, it doesn't need to leave the database at all. Enable the pg_cron extension (Supabase also exposes it as the Cron integration in the dashboard) and schedule a statement:

select cron.schedule(
  'cleanup-expired-sessions',
  '0 3 * * *',
  $$ delete from public.sessions where expires_at < now() $$
);

Run history lands in cron.job_run_details, so you can see failures with a query:

select jobid, status, return_message, start_time
from cron.job_run_details
order by start_time desc
limit 20;

Good for: cleanup, rollups, refreshing materialized views, anything that is a few SQL statements.

Watch out for:

• pg_cron jobs run as a database role and are not subject to the Row Level Security you designed for users. Treat every scheduled statement like admin code and review it as such.
• Long statements hold locks. Delete in batches (where id in (select id ... limit 1000)) instead of one giant delete.
• cron.job_run_details grows forever unless you prune it, so schedule a cleanup for the cleanup table too.

Option 3: pg_cron triggering a Supabase Edge Function

When the job needs HTTP calls or code that isn't SQL, but you want it to live next to the database instead of in your web app, let pg_cron call an Edge Function through the pg_net extension:

select cron.schedule(
  'send-daily-digest',
  '0 7 * * *',
  $$
  select net.http_post(
    url := 'https://YOUR_PROJECT.supabase.co/functions/v1/daily-digest',
    headers := jsonb_build_object(
      'Content-Type', 'application/json',
      'Authorization', 'Bearer ' || (select decrypted_secret from vault.decrypted_secrets where name = 'digest_key')
    ),
    body := '{}'::jsonb
  );
  $$
);

Keep the key in Supabase Vault rather than pasting it into the job text, because job definitions are readable by anyone with database access.

Good for: jobs that other clients don't need to know about, jobs that should keep running even if you redeploy or move the frontend, and webhook retries.

Watch out for: pg_net is asynchronous. The cron job "succeeds" as soon as the request is queued, so a failing function won't show up in cron.job_run_details. Log results from inside the function (to a job_runs table, for example) so you can actually see failures.

Six rules that apply to all three

1. Make every job idempotent. Schedulers can retry or overlap. Running the job twice should do no extra harm; use on conflict do nothing, status columns, or a "last processed id" cursor.
2. Prevent overlapping runs. If a run can take longer than the interval, take an advisory lock (pg_try_advisory_lock) or a row in a job_locks table, and exit if it's held.
3. Process in batches. Small batches finish inside any timeout and are easy to resume.
4. Record every run. A tiny table with job_name, started_at, finished_at, rows_affected and error turns "did the digest go out?" into a query.
5. Keep secrets out of the schedule. Use CRON_SECRET on Vercel and Vault on Supabase.
6. Write the schedule in UTC and say so. Put a comment next to each cron expression with the local time you meant.

Quick decision table

Disclosure: I work on Massvai, an AI app builder that generates full-stack Next.js apps with Supabase and Vercel. Scheduled jobs are one of the first things we wire up in a generated project, which is why this checklist exists.

1. Anything that depends on the signed-in user is dynamic

If a page or Server Component reads cookies to create a Supabase client with @supabase/ssr, it depends on the request. Reading cookies() already opts the route into dynamic rendering, but be explicit for user-specific routes:

export const dynamic = 'force-dynamic'

Never wrap a user-scoped query in unstable_cache or a shared cache key. Row Level Security protects the database, not your cache: if the first result is cached, the second user gets it without RLS ever running.

2. Cache public data on purpose, with a tag

Public, shared data (a pricing table, a blog list, a public gallery) is where caching pays off. Use a Supabase client that does not read cookies (anon key only) and give the cache a tag and a lifetime:

import { unstable_cache } from 'next/cache'

export const getPublicPosts = unstable_cache(
  async () => {
    const { data } = await supabasePublic.from('posts').select('id,title,slug').eq('published', true)
    return data ?? []
  },
  ['public-posts'],
  { tags: ['posts'], revalidate: 300 }
)

3. Revalidate right after the write, in the same Server Action

The "I saved it but the page didn't change" bug almost always means nobody told Next.js the data changed. Call revalidateTag or revalidatePath at the end of the mutation:

'use server'
import { revalidateTag } from 'next/cache'

export async function publishPost(id: string) {
  const supabase = await createServerClient()
  const { error } = await supabase.from('posts').update({ published: true }).eq('id', id)
  if (error) throw error
  revalidateTag('posts')
}

Revalidate only after a successful write, otherwise you throw away a good cache for nothing.

4. Writes from outside Next.js need a webhook into Next.js

If data also changes from the Supabase dashboard, an Edge Function, or a cron job, your Server Actions never run, so nothing revalidates. Add a small Route Handler that calls revalidateTag, protect it with a shared secret, and call it from a Supabase Database Webhook on the relevant table. Without this, the time-based revalidate value is your only safety net.

5. Don't let the router cache fool your testing

On the client, the router keeps visited pages for a short time, so navigating back can show an older render even when the server is fresh. After a mutation from a Client Component, call router.refresh(), or rely on the Server Action's revalidation. When debugging, test with a hard reload before assuming the server cache is wrong.

6. Realtime is for live views, not a replacement for revalidation

Supabase Realtime is great for a feed, a chat, or a job-progress bar that must update without a reload. It doesn't update the server-rendered HTML that the next visitor receives. Use Realtime for the open tab and revalidation for everything else, and subscribe only to rows the user may see, since Realtime respects RLS only when it's enabled on the table.

Quick checklist

• User-specific route: dynamic, no shared cache.
• Public data: cookie-free client, unstable_cache with tags and a lifetime.
• Every write: revalidateTag after success.
• Outside writes: database webhook to a secret-protected revalidate route.
• Client mutations: router.refresh() when needed.
• Live UI: Realtime on top, not instead.

Disclosure: I work on Massvai, an AI app builder that generates full-stack Next.js apps with Supabase and deploys them to Vercel. These rules apply to any Next.js and Supabase project, generated or hand-written.

1. The build fails with supabaseUrl is required.
2. Login works but sends you back to http://localhost:3000/?code=....
3. Production is fine, but every preview deployment fails at the OAuth callback.

All three come from the same two places: how Next.js handles environment variables, and how Supabase decides where to redirect. Here's a setup that handles production, previews and local dev.

1. Environment variables: build time, not runtime

Anything prefixed NEXT_PUBLIC_ is inlined into the client bundle at build time. If the variable isn't set for the environment that runs the build, the bundle contains undefined, and setting it later changes nothing until you redeploy.

In Vercel → Project → Settings → Environment Variables, check that these are enabled for Production, Preview and Development:

The common trap is variables created only for Production. Preview builds then fail with supabaseUrl is required. Open the "..." menu on each variable and tick all environments, then redeploy.

The Vercel ↔ Supabase integration can create these for you. Check the environment scope anyway.

2. Redirect URLs: Site URL vs allow list

Supabase has two settings under Authentication → URL Configuration:

• Site URL: the default redirect when your code doesn't pass redirectTo, and the base used in confirmation and reset emails. If you leave it at http://localhost:3000, production users land on localhost. That's problem 2 above.
• Redirect URLs: an allow list. Any redirectTo you pass must match one of these.

Recommended config:

• Site URL: https://yourdomain.com
• Redirect URLs:
  • http://localhost:3000/**
  • https://*-your-team.vercel.app/** (previews; use your team slug so the wildcard isn't too broad)
  • https://yourdomain.com/**

3. Build redirectTo from the current deployment

Don't hardcode the origin. Use a helper that prefers your production URL, falls back to Vercel's per-deployment URL, then to localhost:

export function getURL() {
  let url =
    process.env.NEXT_PUBLIC_SITE_URL ??          // set in Production only
    process.env.NEXT_PUBLIC_VERCEL_URL ??        // set automatically by Vercel
    'http://localhost:3000/';
  url = url.startsWith('http') ? url : `https://${url}`;
  return url.endsWith('/') ? url : `${url}/`;
}

await supabase.auth.signInWithOAuth({
  provider: 'github',
  options: { redirectTo: `${getURL()}auth/callback` },
});

The key detail: set NEXT_PUBLIC_SITE_URL only for Production. If it's set for Preview too, previews redirect to production, which is the most common "it sends me to the live site" complaint. If you want stable preview URLs per branch, use NEXT_PUBLIC_VERCEL_BRANCH_URL instead.

4. The callback route

With the App Router and @supabase/ssr, exchange the code server-side:

// app/auth/callback/route.ts
import { NextResponse } from 'next/server';
import { createClient } from '@/lib/supabase/server';

export async function GET(request: Request) {
  const { searchParams, origin } = new URL(request.url);
  const code = searchParams.get('code');
  const next = searchParams.get('next') ?? '/';
  if (code) {
    const supabase = await createClient();
    const { error } = await supabase.auth.exchangeCodeForSession(code);
    if (!error) return NextResponse.redirect(`${origin}${next}`);
  }
  return NextResponse.redirect(`${origin}/auth/error`);
}

Use the request's origin, not an env var, so each deployment redirects to itself.

5. OAuth provider settings

For Google, GitHub and others, the provider's callback is Supabase's URL (https://<project>.supabase.co/auth/v1/callback), not your app's. You don't need to add each Vercel preview URL to Google Cloud Console. Only Supabase's allow list needs the wildcard.

6. Don't let a rewrite eat your routes

A catch-all in vercel.json like { "source": "/(.*)", "destination": "/" } is applied before your route handlers at runtime. The build log looks perfect, but /auth/callback silently serves the homepage. Remove it; the App Router doesn't need it.

7. Middleware keeps the session alive

Run the standard @supabase/ssr middleware that calls supabase.auth.getUser() and writes refreshed cookies to both the request and the response. Without it, sessions expire quietly and server components see a logged-out user.

Pre-launch checklist

• Public env vars exist in all three Vercel environments
• Service key is server-only
• NEXT_PUBLIC_SITE_URL is set in Production only
• Supabase Site URL is the production domain
• Redirect URLs include localhost, preview wildcard and production
• Callback uses the request origin
• No catch-all rewrite in vercel.json
• Middleware refreshes cookies
• Email templates use {{ .SiteURL }} / {{ .ConfirmationURL }}, not a hardcoded host

If you'd rather start from a project where this wiring is already done, Massvai generates Next.js + Supabase apps with one-click Vercel deploy and gives you the code to inspect. Either way, it's worth knowing what each setting does, because it's the first thing you'll debug when login breaks on a new domain.