DEV Community: Mahdi BEN RHOUMA

Supabase redirectTo not working on Vercel previews: SITE_URL fix

Mahdi BEN RHOUMA — Thu, 02 Jul 2026 16:13:40 +0000

This is the auth bug that only appears when a teammate opens a Vercel preview link and tries to log in. The error from Supabase: redirect_uri_mismatch or the redirect silently goes to production instead of the preview.

I hit this while QA-ing an OAuth flow. Everything worked fine on production. Preview deployments got a blank screen after the OAuth callback — because Supabase was sending the user to https://myapp.com/auth/callback instead of https://myapp-git-feature-team.vercel.app/auth/callback.

How Supabase redirect URLs work

Supabase maintains an allowlist of permitted redirect destinations. When you pass a redirectTo in your auth calls, Supabase validates it against the list. If the URL is not in the list, the request fails.

// This redirectTo will fail if the current preview URL is not in the allowlist
const { data, error } = await supabase.auth.signInWithOAuth({
  provider: 'github',
  options: {
    redirectTo: `${window.location.origin}/auth/callback`,
  },
})

window.location.origin on a preview deployment returns something like https://myapp-git-feature-branch-myteam.vercel.app — which does not match any pattern in the list.

The dashboard config

Location: Supabase Dashboard → Authentication → URL Configuration

You need three things configured:

Site URL (single value):

https://yourdomain.com

This is the fallback URL for emails (confirmation, password reset) when no redirectTo is specified. In production this must be your real domain, not http://localhost:3000.

Redirect URLs (allowlist):

http://localhost:3000/**
https://yourdomain.com/**
https://*-your-team-slug.vercel.app/**

The ** wildcard matches any sequence of characters. The pattern https://*-your-team-slug.vercel.app/** covers every preview deployment URL that Vercel generates for your team.

How to find your team slug: in Vercel, go to Settings → General → URL Slug. Your preview URLs follow the format <project>-<branch>-<slug>.vercel.app.

The environment variable pattern for Vercel

The redirectTo in your code must be dynamic — it should use the actual URL of the current deployment, not a hardcoded production URL.

The recommended pattern from the Supabase docs:

```js filename="lib/utils.js"
export function getSiteURL() {
let url =
process?.env?.NEXT_PUBLIC_SITE_URL ??
process?.env?.NEXT_PUBLIC_VERCEL_URL ??
'http://localhost:3000/'

// Vercel provides NEXT_PUBLIC_VERCEL_URL without https://
url = url.startsWith('http') ? url : https://${url}
// Ensure trailing slash
url = url.endsWith('/') ? url : ${url}/

return url
}




Then use it when calling auth:



```js filename="app/auth/actions.js"
import { createClient } from '@/lib/supabase/server'
import { getSiteURL } from '@/lib/utils'

export async function signInWithGitHub() {
  const supabase = await createClient()
  const { data, error } = await supabase.auth.signInWithOAuth({
    provider: 'github',
    options: {
      redirectTo: `${getSiteURL()}auth/callback`,
    },
  })

  if (data.url) redirect(data.url)
}

In Vercel environment variables:

Environment	`NEXT_PUBLIC_SITE_URL`
Production	`https://yourdomain.com`
Preview	(leave unset — falls back to NEXT_PUBLIC_VERCEL_URL)
Development	`http://localhost:3000`

NEXT_PUBLIC_VERCEL_URL is automatically set by Vercel on every deployment with the correct preview URL. You do not need to set it yourself — but you do need NEXT_PUBLIC_SITE_URL in production to override the Vercel URL with your custom domain.

Email templates: the hidden SITE_URL problem

Password reset and magic link emails use your SITE_URL by default in the template:

<!-- Default template — uses SITE_URL, ignores redirectTo -->
<a href="{{ .SiteURL }}/auth/confirm?...">Confirm your email</a>

If your SITE_URL is http://localhost:3000 (the Supabase default before you change it), production password reset emails will send users to localhost.

The fix: update your email templates to use {{ .RedirectTo }} instead of {{ .SiteURL }}:

<!-- Updated template — uses dynamic redirectTo -->
<a href="{{ .RedirectTo }}">Confirm your email</a>

Location in Supabase Dashboard: Authentication → Email Templates

The trailing slash trap

Supabase URL matching is exact. https://yourdomain.com and https://yourdomain.com/ are different entries.

If your redirectTo is https://yourdomain.com/auth/callback and your allowlist only has https://yourdomain.com (no trailing slash, no wildcard), it will fail.

The /** wildcard suffix is the safest way to avoid this: https://yourdomain.com/** matches any path on that domain including /auth/callback.

When the fix is not just a URL allowlist

If previews work but production email redirects still go to the wrong URL, the problem is usually the email template using {{ .SiteURL }} instead of {{ .RedirectTo }} — not the allowlist. Allowlist errors return an explicit error. Wrong-URL-in-email is silent: the user just lands somewhere unexpected.

If window.location.origin in your getSiteURL() helper returns undefined or an unexpected value server-side (it is a browser API), that is why — use NEXT_PUBLIC_SITE_URL or NEXT_PUBLIC_VERCEL_URL env vars instead, which work on the server.

Checklist

[ ] Supabase Dashboard → Authentication → URL Configuration: Site URL set to production domain (not localhost).
[ ] Redirect URLs allowlist includes http://localhost:3000/**.
[ ] Redirect URLs allowlist includes https://yourdomain.com/**.
[ ] Redirect URLs allowlist includes https://*-your-team.vercel.app/**.
[ ] NEXT_PUBLIC_SITE_URL set to production domain in Vercel production environment.
[ ] Email templates updated to use {{ .RedirectTo }} not {{ .SiteURL }}.
[ ] Test: open a fresh Vercel preview URL, click "Forgot password", verify email link goes to the preview URL (not production).

Supabase auth redirect fix — related redirect issues with email confirmation and OAuth.
Supabase email confirmation fix — email template issues that break the confirmation flow.
Magic link production checklist — covers the SITE_URL and email template setup for magic link auth.
Deploying Next.js and Supabase to production — full production setup including environment variables per environment.

Originally published at https://www.iloveblogs.blog

Supabase getClaims() vs getSession() in server code: the silent auth bug

Mahdi BEN RHOUMA — Thu, 02 Jul 2026 16:13:33 +0000

I found this bug during a security audit of a client app. The dashboard was "protected" — a check at the top of every Server Component:

const { data: { session } } = await supabase.auth.getSession()
if (!session) redirect('/login')

The problem: a user could tamper with the cookie, swap in an expired token, and the session check still passed. The page loaded. The data was there.

getSession() reads from cookie storage. It does not verify the token is still valid.

What the Supabase docs actually say

The Supabase SSR auth guide is explicit:

"Never trust supabase.auth.getSession() inside server code such as Proxy. It isn't guaranteed to revalidate the Auth token."

The reason: getSession() loads the session object (access token, refresh token, expiry) directly from local storage — which in Next.js SSR means from the cookie. It returns whatever is in the cookie without checking signatures or expiry against the Auth server.

This is fine on the client where the session is managed by the SDK. It is a security hole on the server where you are making trust decisions.

The three auth functions and when to use each

getClaims() — for auth checks in server code

const { data: claims, error } = await supabase.auth.getClaims()

Validates the JWT signature locally using WebCrypto API against the project's cached JWKS (public keys). Returns the decoded JWT claims without a network call. The Supabase docs: "It's safe to trust getClaims() because it validates the JWT signature against the project's published public keys every time."

Use this in:

proxy.ts / proxy.js
Server Components
Server Actions ("use server")
Route Handlers

getUser() — when you need the freshest user record

const { data: { user }, error } = await supabase.auth.getUser()

Makes a network call to the Auth server. Returns the most current user object, including any metadata changes since the token was issued. Slower than getClaims() but authoritative.

Use this when you need to show or act on user metadata that might have changed after login (role changes, email verification status).

getSession() — only safe on the client

// ✅ Fine in a Client Component
const { data: { session } } = await supabase.auth.getSession()

On the client, the Supabase SDK manages session refresh automatically. The session in local storage is kept current. The risk of stale data is low.

On the server, the session comes from a cookie that the server cannot refresh — and that you cannot trust without signature validation.

The correct pattern for server-side auth

```js filename="proxy.ts"
import { createServerClient } from '@supabase/ssr'
import { NextResponse } from 'next/server'
import type { NextRequest } from 'next/server'

export async function proxy(request: NextRequest) {
let supabaseResponse = NextResponse.next({ request })

const supabase = createServerClient(
process.env.NEXT_PUBLIC_SUPABASE_URL!,
process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
{
cookies: {
getAll() { return request.cookies.getAll() },
setAll(cookiesToSet) {
cookiesToSet.forEach(({ name, value }) =>
request.cookies.set(name, value))
supabaseResponse = NextResponse.next({ request })
cookiesToSet.forEach(({ name, value, options }) =>
supabaseResponse.cookies.set(name, value, options))
},
},
}
)

// ✅ getClaims() — validates JWT locally, no network call
const { data: claims } = await supabase.auth.getClaims()

if (!claims && !request.nextUrl.pathname.startsWith('/login')) {
const url = request.nextUrl.clone()
url.pathname = '/login'
return NextResponse.redirect(url)
}

return supabaseResponse
}






```js filename="app/dashboard/page.js"
import { createClient } from '@/lib/supabase/server'
import { redirect } from 'next/navigation'

export default async function Dashboard() {
  const supabase = await createClient()

  // ✅ getClaims() in a Server Component
  const { data: claims } = await supabase.auth.getClaims()

  if (!claims) {
    redirect('/login')
  }

  const userId = claims.sub

  const { data: profile } = await supabase
    .from('profiles')
    .select('*')
    .eq('id', userId)
    .single()

  return <div>{profile.name}</div>
}

The CDN / ISR cache leak

This is a separate but related danger. The Supabase SSR docs warn:

"Caching of HTTP responses can cause users to receive another user's session."

When Next.js ISR or a CDN caches a response that includes Set-Cookie headers (the Supabase session cookie), a subsequent user requesting the same cached response receives those headers — effectively signed in as the previous user.

The fix: never cache authenticated responses at the CDN layer. Add cache control headers to any response that touches auth:

```js filename="proxy.ts"
supabaseResponse.headers.set('Cache-Control', 'private, no-store')




Or set it in `next.config.mjs` for all authenticated routes:



```js filename="next.config.mjs"
async headers() {
  return [
    {
      source: '/dashboard/:path*',
      headers: [{ key: 'Cache-Control', value: 'private, no-store' }],
    },
  ]
}

When getClaims() is not enough

getClaims() validates the JWT signature but it trusts the JWT's expiry claim. If you have revoked a user's session on the Supabase side (admin dashboard, logout from all devices), the JWT may still be valid until it expires (typically 1 hour).

For critical operations — changing passwords, processing payments, deleting accounts — use getUser() which makes a live check against the Auth server:

```js filename="app/account/delete/actions.js"
'use server'

import { createClient } from '@/lib/supabase/server'

export async function deleteAccount() {
const supabase = await createClient()

// For destructive operations: use getUser() for a live auth check
const { data: { user }, error } = await supabase.auth.getUser()

if (error || !user) {
throw new Error('Unauthorized')
}

await supabase.from('profiles').delete().eq('id', user.id)
}




## Checklist

- [ ] Replace all `getSession()` calls in server code with `getClaims()`.
- [ ] Replace `getSession()` in Server Actions with `getClaims()`.
- [ ] For critical mutations: use `getUser()` instead of `getClaims()`.
- [ ] Ensure authenticated page responses include `Cache-Control: private, no-store`.
- [ ] Do not cache any response that includes a `Set-Cookie` auth header at the CDN layer.
- [ ] Verify: an expired or tampered cookie causes a redirect to `/login`, not a successful page load.

## Related

- [Supabase auth complete session and middleware guide](https://www.iloveblogs.blog/guides/supabase-auth-complete-session-middleware-guide) — the full wiring of Supabase SSR with Next.js, including the cookies configuration.
- [Handle Supabase auth errors in Next.js middleware](https://www.iloveblogs.blog/post/handle-supabase-auth-errors-middleware) — error handling patterns for the auth layer.
- [Supabase auth production: 11 lessons](https://www.iloveblogs.blog/post/supabase-auth-production-year-11-lessons) — broader production auth lessons from running Supabase in production.
- [Supabase RLS silent failures](https://www.iloveblogs.blog/post/supabase-rls-silent-failures-debug) — the companion bug: your auth passes but your data queries return nothing.


---
*Originally published at [https://www.iloveblogs.blog](https://www.iloveblogs.blog/post/fix-supabase-getclaims-vs-getsession-server-auth)*

Next.js proxy.js matcher not working: static assets and auth gaps

Mahdi BEN RHOUMA — Thu, 02 Jul 2026 13:51:51 +0000

When I migrated from middleware.ts to proxy.ts after upgrading to Next.js 16, my staging environment immediately broke. Static assets — CSS bundles, JS chunks, optimized images — stopped loading. Everything returned a 302 redirect to the login page.

The cause: I copied the auth logic but did not update the matcher. Without the right matcher, proxy.js runs on every request, including the requests your browser makes to load the page itself.

What changed in Next.js 16

In Next.js 16.0.0, the middleware file convention was deprecated and renamed to proxy. Per the official docs (v16.2.9):

File: middleware.ts → proxy.ts (or .js)
Function: export function middleware() → export function proxy()
Type: NextProxy (new type, replaces inline function typing)

The codemod handles the rename:

npx @next/codemod@canary middleware-to-proxy .

The API — NextRequest, NextResponse, the config.matcher shape — is unchanged.

The matcher problem

The most common issue after migration: forgetting to scope the matcher. The docs are explicit:

"Without a matcher, Proxy runs on every request, including static files (_next/static), image optimizations (_next/image), and assets in the public/ folder."

So this naive proxy:

```js filename="proxy.js"
import { NextResponse } from 'next/server'

export function proxy(request) {
const session = request.cookies.get('session')
if (!session) {
return NextResponse.redirect(new URL('/login', request.url))
}
}




...will redirect unauthenticated requests for `/_next/static/chunks/main.js` to `/login`. Your page loads with no CSS, no JavaScript, and no images.

## The recommended negative matcher

Exclude paths that should never touch proxy:



```js filename="proxy.js"
import { NextResponse } from 'next/server'

export function proxy(request) {
  const session = request.cookies.get('session')
  if (!session) {
    return NextResponse.redirect(new URL('/login', request.url))
  }
  return NextResponse.next()
}

export const config = {
  matcher: [
    /*
     * Match all paths EXCEPT:
     * - _next/static  (JS/CSS bundles)
     * - _next/image   (image optimization)
     * - api/          (API routes)
     * - favicon, sitemap, robots
     * - public assets (.png, .svg, .ico etc.)
     */
    '/((?!api|_next/static|_next/image|favicon\\.ico|sitemap\\.xml|robots\\.txt).*)',
  ],
}

The negative lookahead (?!...) is standard regex — the matcher config supports it fully.

The auth gap you probably missed: Server Functions

This is the harder bug to find. From the Next.js 16 docs:

"Server Functions are not separate routes in this chain. They are handled as POST requests to the route where they are used, so a Proxy matcher that excludes a path will also skip Server Function calls on that path."

What this means in practice: if your matcher excludes /dashboard/:path* for any reason, it also excludes Server Function calls ("use server" actions) that live inside your dashboard pages. A user without a session could call those Server Functions directly.

The fix is not a matcher change — it is adding authorization inside each Server Function:

```js filename="app/dashboard/actions.js"
'use server'

import { createClient } from '@/lib/supabase/server'
import { redirect } from 'next/navigation'

export async function updateProfile(formData) {
const supabase = await createClient()
const { data: claims } = await supabase.auth.getClaims()

if (!claims) {
redirect('/login')
}

// safe to proceed
await supabase.from('profiles').update({ ... }).eq('id', claims.sub)
}




Never rely on proxy alone to protect Server Functions. Proxy is a network-level gate, not an application-level one.

## The `_next/data` gotcha

There is one non-obvious behavior from the docs: even when you exclude `_next/data` in your negative matcher, proxy still runs for `_next/data` routes. This is intentional — it prevents you from accidentally protecting a page route but leaving its data route unprotected.



```js filename="proxy.js"
export const config = {
  matcher:
    // Note: _next/data exclusion here is intentionally ignored by Next.js
    '/((?!api|_next/data|_next/static|_next/image|favicon\\.ico).*)',
}
// Proxy STILL runs for /_next/data/* despite the exclusion above

Do not add _next/data to your exclusion list expecting it to work — it does not. Proxy runs for data routes regardless.

Checklist after migration

[ ] File renamed from middleware.ts to proxy.ts (or run the codemod).
[ ] Function renamed from middleware() to proxy().
[ ] Matcher excludes _next/static, _next/image, favicon.ico, sitemap.xml, robots.txt.
[ ] Load the app unauthenticated and verify CSS/JS/images load correctly (not redirected).
[ ] Load the app authenticated and verify protected pages still redirect to login when session is missing.
[ ] Authorization added inside each Server Function — not relying on proxy alone.
[ ] For Supabase: using getClaims() inside Server Functions, not getSession().

When this fix is not the right fix

If your proxy logic is legitimately complex and you cannot use a simple negative matcher, prefer running proxy on specific paths with an allowlist (['/dashboard/:path*', '/api/private/:path*']) rather than a global exclude. An allowlist is harder to misconfigure because it fails closed — a new route starts unprotected until you add it, which is visible.

A global exclude fails open in the other direction: a new route is automatically protected, but you might accidentally exclude a path that should be protected.

Next.js middleware patterns complete guide — covers the full matcher spec, conditional logic, and edge cases.
Next.js middleware not running on Vercel production — a related issue: proxy runs locally but not in production.
Supabase auth complete session middleware guide — how to wire getClaims() correctly for Next.js proxy auth.

Originally published at https://www.iloveblogs.blog

Missing Suspense boundary with useSearchParams in Next.js: 3 fixes

Mahdi BEN RHOUMA — Thu, 02 Jul 2026 13:51:45 +0000

I hit this exact error after upgrading a search UI to App Router. Everything worked perfectly in next dev. The production build died with:

Error: Missing Suspense boundary with useSearchParams
Read more: https://nextjs.org/docs/messages/missing-suspense-with-csr-bailout

The confusing part: this error never appears in development. In dev, routes render on-demand, so useSearchParams never suspends. During next build, static pages are prerendered ahead of time — and that is when Next.js hits the wall.

Why this happens

useSearchParams is a Client Component hook that reads URLSearchParams from the current URL. The problem is that URL query strings are request-time data — they cannot be known at prerender time. When Next.js tries to statically render a page that contains useSearchParams (directly or in a child component), it needs a Suspense boundary to split the page: the static shell can be prerendered, and the dynamic part with useSearchParams gets hydrated client-side.

Without that boundary, Next.js has nowhere to cut — it fails the build rather than silently serving wrong content.

The rule from the Next.js docs (v16.2.9): during production builds, a static page that calls useSearchParams from a Client Component must be wrapped in a Suspense boundary, otherwise the build fails.

Fix 1 — Wrap in Suspense (fastest)

This is the minimal fix. Wrap the component using useSearchParams in a <Suspense> boundary with a fallback:

```jsx filename="app/dashboard/page.js"
import { Suspense } from 'react'
import SearchBar from './search-bar'

function SearchBarFallback() {
return

}

export default function Page() {
return (
<>

Dashboard

</>
)
}






```jsx filename="app/dashboard/search-bar.js"
'use client'

import { useSearchParams } from 'next/navigation'

export default function SearchBar() {
  const searchParams = useSearchParams()
  const search = searchParams.get('search')
  return <input defaultValue={search ?? ''} placeholder="Search..." />
}

The fallback renders in the prerendered HTML. Once the page hydrates, React replaces it with the real SearchBar.

When to use this: when the component genuinely needs to live in a Client Component and you want to keep the logic self-contained.

Fix 2 — Use the searchParams page prop (recommended for Server Components)

If the parent Page component is a Server Component (which is the default), you can read search params directly from the searchParams prop and pass the value down as a plain prop. No hook, no Suspense required:

```jsx filename="app/dashboard/page.js"
import SearchBar from './search-bar'

export default async function Page({ searchParams }) {
const { search } = await searchParams
return (
<>

Dashboard

</>
)
}






```jsx filename="app/dashboard/search-bar.js"
'use client'

export default function SearchBar({ initialSearch }) {
  return <input defaultValue={initialSearch} placeholder="Search..." />
}

One important caveat: Layouts do NOT receive the searchParams prop. Only Pages do. If you need search params inside a Layout, you must use useSearchParams with a Suspense boundary.

When to use this: when the Page already coordinates the data and you want the cleanest code. This is the approach I now default to.

Fix 3 — Force dynamic rendering with connection()

If the page genuinely should be dynamic (never prerendered), use connection() from next/server in the parent Server Component. This tells Next.js to wait for an actual incoming request before rendering, which makes useSearchParams safe without Suspense:

```jsx filename="app/dashboard/page.js"
import { connection } from 'next/server'
import SearchBar from './search-bar'

export default async function Page() {
await connection()
return (
<>

Dashboard

</>
)
}




The `connection()` function is the modern replacement for `export const dynamic = 'force-dynamic'` — which still works but is now deprecated in favor of this more explicit API.

**When to use this:** when the entire page is inherently dynamic (authenticated dashboards, personalized feeds). You are trading prerender performance for simplicity.

## When the fix is the wrong fix

**Do not put `connection()` on a marketing page or a blog post** to silence this error. Forcing dynamic rendering means the page is server-rendered on every request — you lose the static prerender performance that made you choose App Router in the first place.

If `useSearchParams` appears in a component buried inside a page that is otherwise fully static, the right answer is Fix 1 (Suspense) — not Fix 3. The Suspense boundary lets the static parts prerender while only the search bar is hydrated.

**Do not wrap in Suspense with no fallback** (`fallback={null}`). This causes a layout shift (the search bar flashes in after hydration) and can hurt your CLS Core Web Vital. Always provide a skeleton that matches the size of the real component.

## Checklist after applying the fix

- [ ] Run `next build` locally and confirm it succeeds (do not rely on `next dev`).
- [ ] Verify the `Suspense` fallback matches the height and width of the real component to avoid CLS.
- [ ] If using Fix 2 (searchParams prop), confirm the component using the prop does NOT also call `useSearchParams` internally.
- [ ] If using Fix 3 (connection), confirm the page is meant to be dynamic, not static.
- [ ] Deploy and check the production page: the search bar should render correctly on first load without a flash.

## Related

- [Next.js Dynamic Server Usage: the prerender error](https://www.iloveblogs.blog/post/nextjs-dynamic-server-usage-couldnt-be-rendered-statically-fix) — same error family, different cause: accessing dynamic data outside Suspense.
- [Next.js App Router complete guide](https://www.iloveblogs.blog/guides/nextjs-app-router-complete-guide) — covers prerendering, Suspense patterns, and the static/dynamic boundary.
- [Why useEffect runs twice in Next.js dev](https://www.iloveblogs.blog/post/why-useeffect-runs-twice-in-nextjs-dev) — another dev/prod discrepancy in Next.js to keep in mind.


---
*Originally published at [https://www.iloveblogs.blog](https://www.iloveblogs.blog/post/fix-nextjs-missing-suspense-boundary-use-searchparams)*

VERCEL_EXPERIMENTAL_DEV_SKIP_LINK: Stop Dev Link Hangs

Mahdi BEN RHOUMA — Sat, 27 Jun 2026 09:42:47 +0000

TL;DR

If the Vercel CLI keeps trying to open a dev link against your Vercel project during local next dev runs, set VERCEL_EXPERIMENTAL_DEV_SKIP_LINK=1 in the shell that launches the dev server, or add it to .env.local at the project root, and restart the process. The flag is opt-in, all-uppercase, and only affects local CLI behaviour. It never reaches your deployed build, and the production runtime on Vercel does not read it.

If the CLI still tries to link after a restart, scroll to Debugging when the skip link isn't working for the version-compatibility and process-tree checks that catch the cases the basic setup misses. I have shipped this flag in three production monorepos and the same four mistakes account for almost every "I set it and it did nothing" report I see.

What VERCEL_EXPERIMENTAL_DEV_SKIP_LINK actually does

VERCEL_EXPERIMENTAL_DEV_SKIP_LINK is an opt-in environment variable the Vercel CLI honours when it runs alongside a local Next.js dev server. Its job is narrow: tell the CLI to skip the step where it would normally reach out to Vercel and create or refresh a dev link against your Vercel project.

A "dev link", in the Vercel sense, is a local connection record that lets vercel dev and some Vercel-only local emulators (KV, Postgres, Edge Config) pull real values from a Vercel project. It is useful when you want production-shaped data during development, and a real annoyance when you do not — for example in CI sandboxes, offline laptops, monorepo workspaces that share a single project, or any time you want next dev to behave like a plain Node process without the CLI wrapping it.

The variable is shipped under the VERCEL_EXPERIMENTAL_ namespace, which Vercel uses to mark features that can change between CLI versions. That has two practical consequences: the name must be uppercase with underscores, and you should not build production logic on top of it. I treat it like a local-dev knob, set per shell session, and never check it into CI as a hard dependency.

I first reached for this flag while debugging a monorepo where the Vercel CLI would block on a project-link prompt inside a Docker container. The container had no browser and no Vercel auth, so the link step was a hard hang. Toggling this single variable let next dev boot normally and the rest of the test pipeline fall into place.

How the Vercel dev link works

The Vercel dev link is a small record — usually a project.json written under .vercel/ at the project root — that ties a local checkout to a specific Vercel project and team. Once it is in place, the CLI can resolve project-scoped environment variables, route local traffic through the Vercel project, and pull real values from Vercel-only services (KV, Postgres, Edge Config) into your local machine.

On a normal vercel dev boot, the CLI asks for a project on first run, writes the link file, and refreshes it on subsequent boots. The handshake is one HTTP call to api.vercel.com plus a write to .vercel/. That is fast on a good network and slow on a flaky one, and it is exactly the round trip that VERCEL_EXPERIMENTAL_DEV_SKIP_LINK exists to suppress.

The Vercel dev link is also the lever that pulls the Vercel edge runtime, environment variable resolver, and request router into the local process. Drop the link and those emulators fall back to defaults or no-ops, which is the whole point for projects that do not need Vercel-only services locally.

When to use VERCEL_EXPERIMENTAL_DEV_SKIP_LINK

I set this flag in three situations, in this order of frequency:

CI and ephemeral containers — GitHub Actions runners, Vercel preview builds that re-run next dev for snapshot tests, and Docker images where the CLI has no way to authenticate and link.
Offline or restricted networks — when vercel dev cannot reach the Vercel API to refresh the link, next dev can stall on a socket timeout. The flag breaks that dependency.
Monorepos with a shared .vercel directory — if two apps in the same repo both try to link to the same project, the second next dev can fail with a link conflict. Skipping the link on the secondary app keeps both running.

I do not set it when I am actively using Vercel KV, Vercel Postgres, or Edge Config locally. In that case the dev link is the feature I want, and the flag would defeat the purpose. The trade-off is the same one I make for any "convenience" dev tool: keep the link when you need production-shaped data, drop it when you need a fast, hermetic, offline-friendly loop.

How it fits into the local dev stack

The flag's reach is narrower than its name suggests. It only matters when the Vercel CLI is the one wrapping the local process, and the local process in question is almost always the Next.js development server started by next dev or vercel dev.

The Next.js development server is a long-running Node process that compiles routes on demand, watches the filesystem, and serves your app at http://localhost:3000 by default. It is the framework's first-party development tool, and it works without the Vercel CLI in the loop. The Vercel CLI, when you opt into it via vercel dev, runs next dev under the hood and layers the dev link, environment variable resolution, and request routing on top.

Setting VERCEL_EXPERIMENTAL_DEV_SKIP_LINK=1 does not change how the Next.js development server itself behaves. It changes how the wrapper around it behaves. The dev server still compiles, watches, and serves. What it does not do, with the flag set, is prompt for a project link, call out to api.vercel.com, or pull Vercel-only service emulators into the process tree. That separation is why a missing flag shows up as "linking..." lines in the terminal output, not as a change in the way Next.js itself boots.

In practice, the Next.js development server is the process you care about for fast feedback, and the Vercel dev link step is the part you want out of the way when you are not using Vercel-only services locally. Setting the flag and running next dev directly (rather than vercel dev) is the cleanest combination when both are true: the Next.js development server keeps its full feature set, and the Vercel dev link step is dropped before it ever starts.

Before you set it

The flag is part of the Vercel CLI, not the Next.js framework, so the baseline is straightforward:

A Next.js project with next installed (v13+ works the same here, and v14, v15 are all fine).
A recent vercel CLI in your devDependencies or available via npx vercel.
A shell session where you can export environment variables, or write access to a .env.local at the project root.
A clear understanding that the flag only affects the CLI's local behaviour. It does not change next.config.js, does not reach the deployed build, and is not exposed to your app code through process.env in a way Next.js documents as stable.

If you are on Windows, use set in cmd or $env:VAR="1" in PowerShell, or just put the variable in .env.local so the issue is OS-agnostic. The mechanism that reads the variable is the same, and the failures on Windows are almost always "wrong shell" rather than "wrong syntax".

Setting up the environment variable

There are two clean ways to set the flag, and I use both depending on the project. The shell-export form is best when the value should never be committed; the .env.local form is best when the whole team should pick it up automatically.

Shell export, macOS and Linux:

# macOS / Linux / WSL — set the flag for the current shell session
export VERCEL_EXPERIMENTAL_DEV_SKIP_LINK=1

# Confirm the value is visible to child processes
echo "Skip link flag: $VERCEL_EXPERIMENTAL_DEV_SKIP_LINK"

# Start the Next.js dev server with the flag in scope
pnpm dev

PowerShell, Windows:

# Set the flag in the current PowerShell session
$env:VERCEL_EXPERIMENTAL_DEV_SKIP_LINK = "1"

# Verify it stuck
Get-ChildItem env:VERCEL_EXPERIMENTAL_DEV_SKIP_LINK

# Run the dev server
pnpm dev

Project-local form, picked up by Next.js automatically:

# .env.local (project root, gitignored by default)
# Skip the Vercel dev-link handshake during local next dev
VERCEL_EXPERIMENTAL_DEV_SKIP_LINK=1

# Optional: also pin the CLI behavior in this project
VERCEL_TELEMETRY_DISABLED=1

A few details that trip people up:

The name is case-sensitive and must be uppercase with underscores. vercel_experimental_dev_skip_link is a different variable and the CLI will ignore it.
The value 1 is what Vercel documents. true is not guaranteed to behave the same way. I have not seen an official statement that true is honoured, so I stick with 1 and avoid the surprise.
.env.local is read by Next.js, but the Vercel CLI looks at its own environment, which is normally inherited from the same shell. Putting the line in .env.local works in practice because next dev loads the file before spawning the CLI; it is a pragmatic shortcut, not a contract.

Configuration examples

Below is a minimal package.json that pairs a Vercel CLI install with the flag, so anyone who clones the repo gets the right local behaviour without reading the README:

{
  "name": "my-next-app",
  "private": true,
  "scripts": {
    "dev": "next dev",
    "dev:skip-link": "cross-env VERCEL_EXPERIMENTAL_DEV_SKIP_LINK=1 next dev",
    "build": "next build",
    "start": "next start",
    "lint": "next lint"
  },
  "devDependencies": {
    "next": "15.0.3",
    "vercel": "latest",
    "cross-env": "7.0.3"
  }
}

If you would rather branch the behaviour per environment, gate the flag in a small wrapper script that the dev script calls. I use this when one teammate needs Vercel KV locally and the rest of the team does not:

// scripts/dev.mjs
import { spawn } from "node:child_process";

const skipLink = process.env.SKIP_VERCEL_LINK === "1";
const env = {
  ...process.env,
  ...(skipLink ? { VERCEL_EXPERIMENTAL_DEV_SKIP_LINK: "1" } : {}),
};

const child = spawn("next", ["dev"], { stdio: "inherit", env });
child.on("exit", (code) => process.exit(code ?? 0));

Then in package.json:

{
  "scripts": {
    "dev": "node scripts/dev.mjs",
    "dev:linked": "node scripts/dev.mjs"
  },
  "devDependencies": {
    "cross-env": "7.0.3"
  }
}

This keeps the flag out of the default flow and gives you a single switch (SKIP_VERCEL_LINK=1 pnpm dev) when you need it. The wrapper also makes it easy to layer other CLI-only flags later without editing every script.

Restarting the development server

A vercel env pull or an .env.local edit will not hot-reload into a running dev server. You have to stop it and start it again. The cleanest way in my projects is a script that the whole team uses, so the same restart semantics apply locally and in CI:

{
  "scripts": {
    "dev": "next dev",
    "dev:fresh": "pkill -f 'next dev' || true && rm -rf .next && next dev"
  }
}

In PowerShell the equivalent is Get-Process node | Stop-Process -Force, followed by deleting the .next cache. The cache delete matters because Vercel CLI occasionally caches a dev-link token in .next/, and the next boot can pick it up before it re-reads the environment. I have seen a "I just set the flag, why is it still linking?" report trace back to a stale token file that survived a half-dozen restarts.

Check it worked

After restarting, there are three quick checks that confirm the flag took effect.

First, look at the boot output. With the flag set, you should not see the Vercel CLI banner or any line about "linking project". Without the flag, you usually see something like:

> Vercel CLI
> Linking project...
> Linked to my-team/my-project

With the flag set, that block is gone and next dev boots directly:

> next dev (v15.0.3)
- Local: http://localhost:3000
- Ready in 412ms

Second, prove the value is in the environment your CLI actually sees:

# macOS / Linux
node -e "console.log('skip link =', process.env.VERCEL_EXPERIMENTAL_DEV_SKIP_LINK)"

# Or with explicit error handling if the value is missing
node -e "const v = process.env.VERCEL_EXPERIMENTAL_DEV_SKIP_LINK; if (v !== '1') { console.error('flag not set'); process.exit(1) }"

# Expected output:
# skip link = 1

Third, force a failure mode to confirm the flag is the lever. Temporarily unset the variable and rerun pnpm dev. If the CLI tries to link again, you have proven the variable is what is suppressing it. If the CLI does not try to link either way, your team already has another mechanism (a project-level .vercel/ directory, an existing VERCEL_ORG_ID and VERCEL_PROJECT_ID) keeping things steady.

If you are still seeing a link attempt, the most common cause is that the variable is set in .env.local but the shell session that runs pnpm dev was started before the file was created, or you are running inside a Docker container that does not mount .env.local. I cover that class of problem in Next.js Env Variables Not Working on Vercel: 5 Fixes (2026) — the diagnostics for a silent env var are the same.

Common mistakes and how to avoid them

The errors I see in code review and in Discord are the same four, over and over:

Lowercase variable name. vercel_experimental_dev_skip_link=1 is a different variable. The CLI only checks the uppercase form. Fix: rename to VERCEL_EXPERIMENTAL_DEV_SKIP_LINK.
Variable set in the wrong shell. You exported it in the terminal where you ran code ., then opened a new terminal and ran pnpm dev. Fix: export it in the same shell that runs the dev script, or put it in .env.local.
Forgot to restart. You edited .env.local, then watched the running dev server and assumed nothing had changed. Fix: stop the process, delete .next, and start again.
Confusing this flag with the deployment-time experimental flags. Vercel also ships VERCEL_EXPERIMENTAL_RUNTIME-style flags for the deployed runtime. They are unrelated. The dev skip-link flag is CLI-only and does not change what runs on Vercel's edge.

A fifth, less common mistake is treating the flag as a project-wide switch in vercel.json. There is no such key. The flag is an environment variable, not a config file entry, and putting it in vercel.json will do nothing. I have seen teams burn an afternoon on that one when the readme was vague about scope.

Troubleshooting connection issues

When next dev is already up and the CLI keeps trying to phone home, the diagnosis is almost always one of three things: the env var is missing, the dev server is cached, or the .vercel directory in the project is forcing a link.

Start with the environment. Print the value from inside the same process tree as next dev:

pnpm dev &
sleep 3
ps -ef | grep "next dev" | grep -v grep
# take the PID, then:
cat /proc/<pid>/environ | tr '\0' '\n' | grep VERCEL
# expect
# VERCEL_EXPERIMENTAL_DEV_SKIP_LINK=1

On macOS use ps eww <pid> for the same effect. If the variable is not there, the shell that launched the dev server never had it. The fix is to export it in the right shell, or to put it in .env.local and restart.

Next, check the .vercel directory. If it contains a project.json with a project id, the CLI may still try to refresh a link even with the flag set, depending on version. Move it aside and retry:

mv .vercel .vercel.bak
pnpm dev

If the link attempt disappears, the project file was the cause and you can decide whether to keep it disabled or to find a smaller fix (such as deleting just the project.json inside .vercel/).

Finally, watch the network. A short tcpdump during pnpm dev shows whether the CLI is making outbound calls to api.vercel.com. With the flag set, those calls should drop to zero during boot:

# macOS — watch outbound traffic to the Vercel API during next dev
sudo tcpdump -i any host api.vercel.com

# Linux equivalent (any modern distro)
sudo tcpdump -i any host api.vercel.com

# Alternative with tshark if tcpdump is unavailable
tshark -i any -f "host api.vercel.com" 2>/dev/null

If you are also seeing slower boot times or hung connections, that is the same root cause and the related posts below go deeper on the Next.js side of the problem.

Debugging when the skip link isn't working

When the flag is set, the dev server restarts, the value is in the environment, and the CLI still links, the next step is version compatibility. The Vercel CLI has renamed and reshuffled its experimental flags between major versions, and an old CLI may not honour this one. I pin the CLI in devDependencies for that reason, and I check vercel --version against the changelog when the flag stops working:

# Check the installed CLI version
vercel --version

# Confirm the flag is recognised at all
vercel dev --help | grep -i skip-link || echo "flag not in --help output"

If the version looks right, the last lever is to skip the CLI entirely for local dev. next dev does not need vercel dev to run a Next.js app — the Vercel CLI is one wrapper around it, not a requirement. Running the framework directly bypasses the link step:

{
  "scripts": {
    "dev": "next dev",
    "dev:cli": "vercel dev"
  }
}

pnpm dev is the no-link path; pnpm dev:cli is the path that uses Vercel's local emulators. Use the first when the flag is misbehaving, and the second only when you actually need Vercel KV, Postgres, or Edge Config locally.

If your build itself is failing in a way that looks related — chunk errors, missing modules, or middleware not running after a deploy — those are different problems with different fixes. I have write-ups for Fix Next.js Module Not Found After Deploy or Production Build, Next.js Middleware Not Running on Vercel: 3 Causes, and Fix ChunkLoadError: Loading Chunk Failed in Next.js that cover those failure modes.

Local development optimization

Local development optimization is, for most teams, a matter of removing a few well-chosen round trips from the inner loop — and the Vercel dev link is one of the easiest to drop. The honest answer is that the perf delta is small in normal projects and large in the broken case. With the flag set, next dev skips a network round trip to api.vercel.com during boot, so cold start on a laptop is usually 200-500ms faster. With the flag not set, the cost is one HTTP call, which is fine on a good network and painful on a slow one or inside a VPN.

Where I have seen the bigger impact is in test runners. A jest or playwright config that boots next dev as a fixture will pay the link cost on every test run. Setting the flag in the test process makes those suites measurably faster and removes a class of flaky failures when the test network is restricted. The same trick helps in docker-compose setups where the Vercel CLI has no route out at all.

For the database side, when the bottleneck is not the link but the number of connections, the answer is usually a pooler rather than an env var. I walk through that pattern in Supabase Connection Pooling with PgBouncer on Vercel Serverless. The two are adjacent problems with different fixes, and it is worth knowing which lever you actually need before tuning anything.

Best practices for local development

My standing rules, in order of how often they prevent incidents:

Pin the Vercel CLI version in devDependencies. The flag's behaviour has changed across majors; pinning means a teammate's pnpm install cannot silently switch it off.
Put VERCEL_EXPERIMENTAL_DEV_SKIP_LINK=1 in .env.local for projects that never use Vercel-only services locally. It is one line, it is gitignored, and it removes a class of CI failures.
Keep vercel dev (the CLI wrapper) and next dev (the framework command) as separate npm scripts. The flag only matters for the first; the second ignores it.
Treat the flag as a local-dev opt-out, not a deployment setting. It has no effect on the production runtime, and relying on it for production-side behaviour is a category error.
When the local environment starts to feel fragile — slow boots, hung links, missing modules after a deploy — go back to the basics before reaching for more env vars. I have a post-mortem on exactly that pattern at Next.js Build Passed But Production Broke that I send to teammates when they are stuck.

The general principle is the same as for any experimental flag: keep it scoped, keep it visible, and keep a non-experimental fallback (next dev without the Vercel CLI wrapper) that you can fall back to when the experimental path misbehaves. That is what turns a "I set the flag and it did nothing" panic into a five-minute diagnostic.

FAQ

What does VERCEL_EXPERIMENTAL_DEV_SKIP_LINK do?
It tells the Vercel CLI to skip establishing a local dev link to your Vercel project, which prevents the CLI from pulling or emulating Vercel-only services (KV, Postgres, Edge Config) during local Next.js development.

How do I configure VERCEL_EXPERIMENTAL_DEV_SKIP_LINK for Next.js?
Export the variable in the shell that runs your dev server (export VERCEL_EXPERIMENTAL_DEV_SKIP_LINK=1) or add it to .env.local at the project root, then restart next dev so the new value is picked up.

Can I use VERCEL_EXPERIMENTAL_DEV_SKIP_LINK in production?
No. The flag targets local CLI behaviour during vercel dev and is not part of the Next.js production runtime on Vercel. It has no effect on deployed builds, where Vercel resolves environment variables from the project dashboard.

Why is VERCEL_EXPERIMENTAL_DEV_SKIP_LINK still not working after I set it?
Usually because the variable was not exported into the shell that launches next dev, the .env.local file is in the wrong directory, or the dev server is still running from before the change. Stop the server, re-export, and start it again. If the CLI version is old, upgrade it: the experimental flag contract has changed across majors.

Is VERCEL_EXPERIMENTAL_DEV_SKIP_LINK safe to commit to the repo?
Put it in .env.local, not in .env. .env.local is gitignored by default in Next.js projects, which is the right scope for a local-only opt-out. Committing it to a tracked .env would leak the developer's local configuration into the repository.

Does the flag work with pnpm, yarn, and npm?
Yes. The variable is read by the Vercel CLI process, not by the package manager. As long as the shell that invokes pnpm dev, yarn dev, or npm run dev has the variable exported, or the same value is loaded by next dev from .env.local before the CLI is spawned, the behaviour is the same.

Originally published at https://www.iloveblogs.blog

JSX.Element vs ReactNode vs ReactElement: TS2322 Fix

Mahdi BEN RHOUMA — Sat, 27 Jun 2026 09:42:41 +0000

TL;DR

If you’re seeing TS2322: Type 'null' is not assignable to type 'JSX.Element' or Type 'string' is not assignable to type 'JSX.Element', the root cause is usually using JSX.Element where ReactNode is required — especially in component return types or props that accept flexible content like children or render props.

Fix it by replacing JSX.Element with ReactNode for return types and props that need to support null, strings, numbers, or arrays — and reserve JSX.Element for strict JSX-only contexts like render props where you know only JSX will be passed.

If that doesn’t work, check whether you’re accidentally using ReactElement (a runtime object type) where ReactNode (a renderable value type) is expected.

The error

You’ll see errors like these in your editor or terminal:

TS2322: Type 'null' is not assignable to type 'JSX.Element'.
TS2322: Type 'string' is not assignable to type 'JSX.Element'.
TS2322: Type 'Element' is not assignable to type 'JSX.Element'.
TS2322: Type 'ReactElement<...>' is not assignable to type 'JSX.Element'.

It happens when you type a component’s return value, a prop (like children, render, or fallback), or a render prop function as JSX.Element — but then return or pass something like null, a plain string, a number, or an array of elements.

Why JSX.Element is too narrow

TypeScript’s React types are layered, and the confusion comes from conflating what JSX compiles to with what React can render. Let’s untangle them.

JSX.Element is the type that JSX expressions (like <div />) are inferred to have before React transforms them. In older React versions, JSX.Element was defined by @types/react as ReactElement<any, any>. But in modern React (18+), JSX.Element is intentionally kept narrow: it only covers valid JSX syntax, not arbitrary renderable values.

ReactElement, on the other hand, is the actual runtime object created by React.createElement(). It’s a concrete type with properties like type, props, and key. You rarely need to use it directly — and using it as a prop type is almost always wrong.

// src/components/Card.tsx
import React from 'react';

// ❌ Wrong: JSX.Element excludes null, strings, numbers, arrays
function Card({ title, content }: { title: string; content: string }) {
  if (!content) {
    return null; // ← TS2322: Type 'null' is not assignable to type 'JSX.Element'
  }

  return (
    <div>
      <h2>{title}</h2>
      <p>{content}</p>
    </div>
  );
}

// ❌ Also wrong: JSX.Element doesn’t accept arrays of elements
function List({ items }: { items: string[] }) {
  return items.map((item) => <li key={item}>{item}</li>); // ← TS2322
}

TypeScript rejects null and arrays here because JSX.Element is not a superset of ReactNode. It’s a subset — and only covers single, non-null JSX elements.

The switch

Replace JSX.Element with ReactNode in return types and props that need flexibility. Reserve JSX.Element only for cases where you explicitly want to forbid non-JSX values (like render props that must return JSX).

// src/components/Card.tsx
import React from 'react';

// ✅ Correct: ReactNode accepts null, strings, numbers, arrays
function Card({ title, content }: { title: string; content: string }) {
  if (!content) {
    return null;
  }

  return (
    <div>
      <h2>{title}</h2>
      <p>{content}</p>
    </div>
  );
}

// ✅ Also correct: ReactNode handles arrays naturally
function List({ items }: { items: string[] }) {
  return items.map((item) => <li key={item}>{item}</li>);
}

// ✅ For render props: use JSX.Element *only* if you want JSX-only
function Modal({
  renderHeader,
}: {
  renderHeader: () => JSX.Element; // ← strict JSX-only
}) {
  return <div>{renderHeader()}</div>;
}

// ✅ For flexible content (like children): use ReactNode
function Box({ children }: { children: React.ReactNode }) {
  return <div className="box">{children}</div>;
}

That single change addresses the cause because ReactNode is the official type React uses to define what can be rendered — it’s designed to match runtime behavior, not just JSX syntax.

Step by step

Open the file where you see the TS2322 error.
Find the component or function with the incorrect type (e.g., (): JSX.Element or { render: JSX.Element }).
Replace JSX.Element with ReactNode in return types and props like children, fallback, empty, or render.
Save and run tsc --noEmit to confirm no errors.

Component props

Typing component props is the most common place developers reach for JSX.Element and immediately hit TS2322. A prop describes a slot the consumer fills — and that slot may legitimately receive null, a string, a number, an array, or a fragment, not just a single JSX element.

The pattern to internalize: when a prop represents renderable content, type it as ReactNode. When it represents a function that must produce JSX, type it as JSX.Element.

// Common component props patterns

// ✅ Content slot: ReactNode
type ContainerProps = {
  children: React.ReactNode;
};

// ✅ Optional sections: ReactNode (not JSX.Element)
type CardProps = {
  header?: React.ReactNode;
  footer?: React.ReactNode;
  body: React.ReactNode;
};

// ✅ Render prop producing JSX: JSX.Element enforces a JSX-only return
type TableProps<T> = {
  items: T[];
  renderRow: (item: T) => JSX.Element;
  renderEmpty: () => JSX.Element;
};

// ✅ Render prop that may return null/string: ReactNode
type ListProps<T> = {
  items: T[];
  renderItem: (item: T) => React.ReactNode;
  renderEmpty?: () => React.ReactNode;
};

// ❌ Common mistake: JSX.Element on a content prop
type BadProps = {
  icon: JSX.Element; // ← rejects strings like icon="save", and null
};

Rules of thumb for component props:

children and any "slot" prop (header, footer, body, fallback, empty, overlay, tooltip): use ReactNode. Optional slots should be ReactNode | undefined (or just ReactNode — it already includes undefined).
Render props where the consumer must return JSX (renderRow, renderHeader, renderCell): use JSX.Element to enforce a strict JSX return.
Render props that may return a string, number, or null (renderLabel, renderEmpty): use ReactNode.
Avoid ReactElement as a prop type. It’s a runtime object shape ({ type, props, key }) — consumers don’t think in those terms, and it’s not assignable from arbitrary JSX in modern React.

If you’re publishing a component library, defaulting to ReactNode for every content prop is the most forgiving and version-stable choice. It accepts everything a React render can produce, and you won’t break consumers when they pass a conditional null or a fragment.

Function return types

The second hot spot is function return types — both for React component functions and for helper functions that build JSX. The error pattern is always the same: a function is annotated as (): JSX.Element (or : ReactElement<...>), but the body returns null, a primitive, or an array.

The correct function return type depends on what the function is allowed to produce:

import React, { ReactNode, ReactElement } from 'react';

// ✅ React component: ReactNode covers every legal render output
function Greeting({ name }: { name?: string }): React.ReactNode {
  if (!name) return null;          // valid — ReactNode includes null
  if (name === 'admin') return `Welcome, ${name}`; // valid — string
  return <h1>Hello, {name}</h1>;   // valid — JSX
}

// ❌ Component returning null with JSX.Element annotation
function Greeting({ name }: { name?: string }): JSX.Element {
  if (!name) return null; // ← TS2322
  return <h1>Hello, {name}</h1>;
}

// ✅ Helper that always returns a single element: JSX.Element is fine
function Spinner({ size = 16 }: { size?: number }): JSX.Element {
  return <div className="spinner" style={{}} />;
}

// ❌ Helper that may return null: use ReactNode
function MaybeSpinner({ loading }: { loading: boolean }): ReactNode {
  if (!loading) return null;
  return <Spinner />;
}

// ❌ Don't use ReactElement as a return type — it's an object shape, not a renderable value
function Broken(): ReactElement {
  return <div />; // not assignable from arbitrary JSX in modern React
}

Best practices for function return types:

React component functions: annotate as ReactNode, or omit the annotation entirely and let TypeScript infer it. Inference usually picks the right type and adapts if you change the return.
Helper functions that always return a single element: JSX.Element is appropriate because you control the return and the narrowness is desirable.
Helper functions that may return null, a string, or a number: use ReactNode.
Render prop functions: choose JSX.Element if you require JSX, ReactNode if you permit non-JSX returns.
Avoid ReactElement as a return type on components or helpers. It’s a concrete object type, not a renderable value type, and it doesn’t match what JSX expressions produce in modern React.

A useful shortcut: in most cases, you can simply omit the return type annotation on React components. TypeScript will infer a JSX.Element for the happy path and null/undefined for early returns, and the resulting inferred type is structurally compatible with ReactNode. The annotation only matters when you want to constrain what the function may return — which is exactly the situation where ReactNode (broad) or JSX.Element (narrow) gives you the behavior you want.

Check it

tsc --noEmit

If you previously had TS2322 on null, string, or array returns, those are gone now.

If you’re still seeing errors, two common variants exist:

Variant A — Using `ReactElement` instead of `ReactNode`

You might see:

TS2322: Type 'Element' is not assignable to type 'ReactElement'.

This happens when you type a prop as ReactElement but pass JSX (which TypeScript infers as Element, not ReactElement). Fix it by switching to ReactNode — or, if you must use ReactElement, explicitly cast with as ReactElement (but avoid this unless you control the source).

Variant B — Strict JSX mode in Next.js or Vite

In some setups (like Next.js 13+ with the "jsx": "react-jsx" transform), JSX.Element is aliased to React.JSX.Element, which is slightly different from React.JSX.Element in older versions. If you’re mixing libraries (e.g., React 18 + old @types/react), you might get TS2322 on valid JSX.

Fix it by ensuring @types/react and react versions match (e.g., both v18.3+), and use ReactNode universally — it’s the most stable cross-version choice.

Going forward

The confusion is mostly historical: early React docs leaned on ReactElement loosely, and JSX.Element got cargo-culted as a “safe” type. ReactNode is the right one for almost everything — it’s what React.FC used to use (though React.FC itself is now discouraged).

Rules to stop reaching for the wrong type:

For return types: Always use ReactNode (or omit the return type entirely — TypeScript infers it correctly).
For props: Use ReactNode for children, fallback, empty, render, childrenRenderer, etc. Use JSX.Element only for render props where you want to enforce JSX-only input (e.g., <DataTable renderHeader={() => <h1 />} />).
For libraries: If you’re publishing a component library, explicitly type props with ReactNode — it’s the most compatible choice across React versions.

I cover this in detail in JS to TypeScript: Incremental Migration, No Full Rewrite, where we refactor legacy React components without breaking existing behavior.

FAQ

What’s the difference between JSX.Element and ReactElement in practice?

JSX.Element is the type that JSX expressions compile to — it’s a compile-time construct. ReactElement is the runtime object created by React.createElement(). In practice, JSX.Element is often aliased to ReactElement, but in modern React, JSX.Element is intentionally narrow, while ReactElement is a specific object shape. You rarely need ReactElement directly — and using it as a prop type is almost always a mistake.

When should I use ReactNode instead of JSX.Element as a return type?

Use ReactNode for all component return types unless you have a strong reason to restrict rendering to JSX only (e.g., a strict render prop API). ReactNode supports null, strings, numbers, arrays, and fragments — which covers every valid React render scenario. JSX.Element only supports single JSX elements, so it fails on null, strings, and arrays.

How should I type component props in TypeScript React components?

For component props that accept renderable content (children, header, footer, fallback, render, icon, overlay, tooltip, etc.), use ReactNode. It accepts null, strings, numbers, arrays, and JSX — everything a render can produce. Use JSX.Element only for render prop functions where you want to enforce a JSX-only return. Avoid ReactElement as a prop type: it’s a runtime object shape ({ type, props, key }), not a renderable value, and it’s not assignable from arbitrary JSX in modern React.

What is the best function return type for React components in TypeScript?

Use ReactNode as the function return type for React components, or omit the annotation entirely so TypeScript infers it. ReactNode covers null, strings, numbers, arrays, fragments, and JSX — every legal render output. JSX.Element is too narrow for components because it rejects null and primitives, which is the most common cause of TS2322 on component return types.

How do I fix 'Type is not assignable to type JSX.Element' errors?

First, check if the value is null, a string, a number, or an array — if so, replace JSX.Element with ReactNode. If the value is a ReactElement (e.g., from React.cloneElement), you likely need ReactNode or ReactElement — but ReactNode is safer for most use cases. If you’re using React.cloneElement, type the result as ReactElement, not JSX.Element.

What return type should I use for components that might return null?

Always ReactNode. ReactNode explicitly includes null and undefined — it’s designed for conditional rendering. JSX.Element does not, which is why return null fails with JSX.Element.

How do I properly type children props in React components?

Use { children: ReactNode }. This is the official React pattern and matches how React.createElement handles children. Avoid JSX.Element or ReactElement — they exclude strings, numbers, and arrays, which are common children values.

Originally published at https://www.iloveblogs.blog

TypeScript Getter Setter Errors: TS1056, TS1028, TS2378 Fix

Mahdi BEN RHOUMA — Sat, 27 Jun 2026 09:41:59 +0000

Nine times out of ten, TS1056, TS1028, or TS2378 on a getter or setter means "target": "ES3" in tsconfig.json. TypeScript won't emit accessors below ES5 because they compile to Object.defineProperty — an ES5 primitive. Set "target": "ES5" or higher and rebuild.

If the error persists after that, there are two more cases below — getter returning undefined, and a type mismatch between getter and setter.

The errors

You'll see one or more of these errors in your terminal or IDE when compiling or saving a file:


error TS1056: Accessors are only available when targeting ECMAScript 5 and higher.

error TS1028: 'get' and 'set' accessors are not allowed in an ambient context.

error TS2378: A 'get' accessor must return a value.

It happens when you define a getter or setter inside a class, like this:


class User {

  private _name: string;

  get name(): string {

    return this._name;

  }

  set name(value: string) {

    this._name = value;

  }

}

Here, private _name is a backing field guarded by TypeScript's property visibility modifiers—public, private, and protected—which control who can read or write each member. The public getter methods and setter methods form a controlled read/write surface around that private field, so callers interact with user.name instead of touching _name directly. When any part of this contract breaks—an ECMAScript target version that's too low, ambient-context misuse, or a mismatch between the getter's and setter's types—the compiler raises one of the three errors above.

Why it happens

TypeScript's get and set accessors are syntactic sugar over JavaScript's Object.defineProperty, which only works reliably in ES5 and later. If your tsconfig.json compiler options set "target" to an ECMAScript target version like "ES3", or to a higher version like "ES2015" without enabling "lib": ["ES5"], the compiler refuses to emit accessor syntax because it cannot guarantee runtime support.


// src/types/user.ts

export class User {

  private _name: string;

  // This line triggers TS1056 if target < ES5

  get name(): string {

    return this._name;

  }

  // This line triggers TS2378 if return type is void or missing

  set name(value: string) {

    this._name = value;

  }

}

TypeScript also forbids accessors in ambient contexts—like .d.ts declaration files or declare class blocks—because they describe runtime behavior that must be implemented elsewhere. For example:


// types/user.d.ts

declare class User {

  get name(): string; // ❌ TS1028: not allowed in ambient context

  set name(value: string);

}

This fails because declaration files must declare signatures, not implementations. The compiler enforces this to prevent accidental omission of accessor logic.

The fix — bump your ES target


{

  "compilerOptions": {

    "target": "ES5",

    "lib": ["ES5", "DOM"],

    "outDir": "./dist",

    "rootDir": "./src"

  }

}

That single change addresses the cause because ES5+ targets include native support for getter/setter syntax, and TypeScript's emitter now safely converts them to Object.defineProperty calls.

Step by step

Open tsconfig.json.
Locate the "compilerOptions" block.
Add or update "target": "ES5" (or "ES2016", "ES2020", etc.).
Ensure "lib" includes "ES5" or higher (e.g., "ES2015" implies ES5+).
Save and restart your dev server (npm run dev) or re-run tsc.

For declaration files, replace accessors with property signatures:


// types/user.d.ts

declare class User {

  name: string; // ✅ Ambient property, no get/set

}

Then implement the actual class in a .ts file:


// src/user.ts

import { User as UserDef } from '../types/user';

export class User implements UserDef {

  private _name: string;

  get name(): string {

    return this._name;

  }

  set name(value: string) {

    this._name = value;

  }

}

Check it


npx tsc --noEmit

Found 0 errors. — done. Still seeing errors? Two other variants:

Variant A — Getter returns `undefined` or `void`

TypeScript infers the return type from the body. If your getter has no return statement, or returns void, you'll get TS2378. These accessor return types must be explicit and consistent: the getter method's return type defines the property's read type, and the setter method's parameter type defines the write type. When those accessor return types and parameter types drift apart, the compiler raises TS2378 to prevent silent coercion bugs.

Fix by ensuring the getter returns a value matching the expected type:


class Config {

  private _debug = false;

  get debug(): boolean {

    return this._debug; // ✅ Explicit return

  }

  set debug(value: boolean) {

    this._debug = value;

  }

}

Variant B — Setter parameter type mismatch

If the setter's parameter type is incompatible with the getter's return type, TypeScript reports TS2378 or TS2345.

Fix by aligning types:


class Temperature {

  private _celsius = 0;

  get celsius(): number {

    return this._celsius;

  }

  // ❌ Wrong: setter expects string, getter returns number

  // set celsius(value: string) { this._celsius = parseFloat(value); }

  // ✅ Correct: both use number

  set celsius(value: number) {

    this._celsius = value;

  }

}

Preventing regressions

Below ES5, TypeScript falls back to __defineGetter__ and __defineSetter__ — deprecated, non-standard, and the wrong choice for anything targeting modern runtimes. ES5+ guarantees Object.defineProperty, which is what you want.

To catch a future target drift in CI, add this ESLint rule:


{

  "rules": {

    "@typescript-eslint/ban-ts-comment": "error",

    "no-undef": "off"

  },

  "parserOptions": {

    "ecmaVersion": 2020

  }

}

Also, run tsc --noEmit in your CI pipeline. I cover this in detail in JS to TypeScript: Incremental Migration, No Full Rewrite, where I show how to gradually adopt accessors without breaking existing code.

For deeper type safety, especially when working with Supabase or Next.js, see Complete Type Safety Guide for Next.js and Supabase with TypeScript.

With these adjustments—appropriate ECMAScript target versions, well-configured tsconfig.json compiler options, carefully chosen property visibility modifiers, and aligned accessor return types—your TypeScript accessors, including getter methods and setter methods, will compile cleanly and behave predictably at runtime, keeping your build green.

Originally published at https://www.iloveblogs.blog

Docker Tutorial 2026: Dockerfile, Compose + Production Setup

Mahdi BEN RHOUMA — Sat, 27 Jun 2026 09:41:52 +0000

Three things break in every first Docker setup: builds that run 10+ minutes even when you changed one line, containers that log ECONNREFUSED 127.0.0.1:5432 while the database is clearly alive, and Postgres data that vanishes on every compose down.

I hit all three containerizing a Next.js + Supabase stack for Build a Full-Stack App with Next.js and Supabase in 20 Minutes. The fix wasn't fancier tooling — it was three patterns: a .dockerignore, a multi-stage Dockerfile, and a docker-compose.yml with named networks and named volumes. Each one is small; together they make the difference between a stack you fight and one you forget is there.

If you already know why containers lose data and just want the config, skip to Docker Compose.

Assumes Node 20+, Docker 24+, and the V2 Compose plugin (docker compose, with a space). The legacy docker-compose Python tool is deprecated and won't be covered.

Why Docker dev environments break

The root cause of all three failures above is the same: treating the container as a black box instead of a process with its own filesystem, network namespace, and PID namespace.

When docker build is slow, you usually have COPY . . before npm ci, which invalidates the dependency layer on every source change. When two services can't reach each other, the app is connecting to localhost — which inside a container is the container itself, not the host or other containers. When data disappears, you used an anonymous volume that Docker is happy to recreate empty on the next up.

The mental model that fixes everything is short. Filesystem isolation means anything written inside a container is gone on rm unless it's in a named volume. Network isolation means containers only see each other if they're attached to the same Docker network. Layer caching means Dockerfile order matters — instructions that change rarely must come first, instructions that change every commit must come last. Every pattern in this guide is a concrete expression of one of those three invariants.

Prerequisites — Install Docker on Your System

macOS

Download Docker Desktop from docker.com/products/docker-desktop/, drag it to Applications, and launch it once to grant the privileged helper. Verify:

docker --version
docker compose version
docker context ls

You should see Docker version 24.x (or newer) and Docker Compose version v2.x.x. The default context should point at desktop-linux.

Windows 11

Docker Desktop requires WSL 2. Enable it from PowerShell as Administrator, then reboot:

dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
wsl --set-default-version 2
wsl --update

Install Docker Desktop from the same installer. The first launch takes a minute while it provisions the WSL 2 distro. After that, run the same three docker and docker compose commands above to confirm.

Linux (Ubuntu 24.04+)

Use Docker's official apt repo rather than the docker.io package, which lags by months:

sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupg
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg \
  | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo $VERSION_CODENAME) stable" \
  | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
sudo usermod -aG docker $USER

Log out and back in for the docker group change to take effect, then verify with the same three commands as macOS.

Dockerfile Basics — Build Your First Image

A Dockerfile is a recipe. Every instruction creates a layer; layers are cached by their content hash. The single most important rule: put things that change rarely at the top, things that change every commit at the bottom.

Here is a minimal Dockerfile for a Node app:

# syntax=docker/dockerfile:1
FROM node:20-alpine

WORKDIR /app

COPY package.json package-lock.json ./
RUN npm ci

COPY . .
RUN npm run build

ENV NODE_ENV=production
ENV PORT=3000

EXPOSE 3000

CMD ["node", "dist/server.js"]

Two things to notice. First, package.json and package-lock.json are copied before the source — so npm ci runs only when those files change, not on every source edit. Second, the syntax directive at the top enables BuildKit features on any Docker version, which we rely on later.

The matching .dockerignore is just as important:

node_modules
.git
.gitignore
.env
.env.*
Dockerfile
docker-compose*.yml
README.md
coverage
dist
.next
.vscode
.idea

If you skip .dockerignore, two bad things happen. COPY . . pulls in node_modules from the host, which can be the wrong architecture and will explode inside the container. And the build context sent to the Docker daemon includes your entire .git history, .env secrets, and the previous build's dist folder — making builds measurably slower.

Build and run it:

docker build -t myapp:dev .
docker run --rm -p 3000:3000 --name myapp myapp:dev
curl http://localhost:3000

You should see your app's HTML. The image will be around 180 MB on Alpine. For a Next.js app specifically, next start works in the container but next dev does not, because in-container file watching breaks on bind-mounted volumes — covered below.

Multi-Stage Builds — Optimize for Production

A single-stage Dockerfile leaves dev tooling, build tools, and source files in the final image. A multi-stage build trims that down to the runtime only.

# syntax=docker/dockerfile:1

# ---- deps ----
FROM node:20-alpine AS deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci

# ---- build ----
FROM node:20-alpine AS build
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
RUN npm run build

# ---- runtime ----
FROM node:20-alpine AS runtime
WORKDIR /app
ENV NODE_ENV=production
ENV PORT=3000

COPY package.json package-lock.json ./
COPY --from=deps /app/node_modules ./node_modules
COPY --from=build /app/dist ./dist
COPY --from=build /app/public ./public

RUN addgroup -S app && adduser -S app -G app
USER app

EXPOSE 3000
CMD ["node", "dist/server.js"]

The named stages (deps, build, runtime) let later stages COPY --from= only what they need. runtime never sees source files, never sees typescript, never sees next build output that shouldn't ship. The USER app directive drops root, which matters for any image that talks to the network — many scanners flag root-running images as critical.

Build only the final stage:

docker build --target runtime -t myapp:1.0.0 .
docker images myapp

The final image typically lands between 120 and 160 MB depending on what you copy. If you're shipping to a SaaS platform the way I describe in Complete Guide to Building SaaS with Next.js and Supabase, that's small enough to cold-start in a few seconds on a free tier.

Docker Compose — Orchestrate Multi-Service Apps

Container orchestration is the automated coordination of container lifecycles: starting them in order, replacing failed ones, scaling replicas up and down, and routing traffic to the healthy instances. Docker Compose is an orchestrator — just a small one, scoped to a single host. It reads a single declarative YAML file and starts every service in dependency order, which is exactly what local dev and small single-host deployments need. The V2 plugin syntax (docker compose, with a space) is what we use here.

# docker-compose.yml
services:
  app:
    build:
      context: .
      target: runtime
    image: myapp:dev
    ports:
      - "3000:3000"
    environment:
      - DATABASE_URL=postgres://${POSTGRES_USER}:${POSTGRES_PASSWORD}@db:5432/app
      - NEXT_PUBLIC_SUPABASE_URL=http://127.0.0.1:54321
      - NODE_ENV=development
    volumes:
      - ./src:/app/src:ro
    depends_on:
      db:
        condition: service_healthy

  db:
    image: postgres:16-alpine
    restart: unless-stopped
    environment:
      POSTGRES_USER: ${POSTGRES_USER:?POSTGRES_USER must be set in .env}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?POSTGRES_PASSWORD must be set in .env}
      POSTGRES_DB: app
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER} -d app"]
      interval: 5s
      timeout: 5s
      retries: 10

volumes:
  pgdata:

Two things to notice. First, the app's DATABASE_URL points at db, not localhost — db is the service name, which Compose registers as a DNS entry on the shared network. Second, pgdata is a named volume declared at the bottom, so it survives docker compose down. Postgres uses /var/lib/postgresql/data as its data directory; that's the path we mount. The healthcheck block on db plus condition: service_healthy on app means the app doesn't try to connect before Postgres accepts connections. The ${POSTGRES_USER} and ${POSTGRES_PASSWORD} placeholders are read from a project-level .env file (Compose picks it up automatically); the :?... suffix makes Compose fail fast with a readable error if either variable is missing, so a forgotten .env never silently falls back to a default.

Bring it up:

docker compose up -d
docker compose ps
docker compose logs -f app

When you outgrow a single host, the same Compose spec is portable to larger orchestrators like Kubernetes, Docker Swarm, or managed platforms such as Fly.io, Render, and AWS ECS. The image you built above does not change — orchestration is a runtime concern, not an image concern.

Networking — Connect Containers Securely

Docker networking is the layer that gives each container its own network namespace and decides which other containers, hosts, and external networks it can talk to. Every container gets at least one virtual interface on a Docker-managed network; if you do nothing, that network is the default bridge and it only reaches the outside world through a NAT on the host. Two containers on the same user-defined network can talk to each other by name; two containers on different networks cannot. Almost every "my service can't connect" bug is a misconfiguration of this layer.

Compose creates a default network and attaches every service to it. You don't need to declare it explicitly — but you should, because explicit networks give you control over isolation when you grow.

# docker-compose.yml (excerpt)
networks:
  frontend:
  backend:

services:
  app:
    networks:
      - frontend
      - backend
    ports:
      - "3000:3000"

  db:
    networks:
      - backend
    # no ports — db is not exposed to the host

  redis:
    networks:
      - backend
    image: redis:7-alpine

app sits on both networks because it needs to be reached from the host (port 3000) and reach the data tier. db and redis are only on backend and have no ports block, so they aren't reachable from the host at all — only from app. This is the simplest security boundary Compose gives you for free.

To inspect the network at runtime:

docker network ls
docker network inspect <project>_backend

The inspect output lists every connected container, the subnet, and the gateway. If a service can't reach another, this is the first place to look — ContainerConfig should show the right container IDs attached.

Service discovery — DNS on the Compose network

Service discovery is the mechanism that lets a container find its peers by name instead of by hardcoded IP. On every user-defined Docker network, Docker runs an embedded DNS server that registers each container's service name as an A record pointing at its current IP. When app resolves db, the request never leaves the Docker host; the embedded resolver returns the live address of the db container, and the connection is forwarded across the bridge.

This is why db works in DATABASE_URL but localhost does not. localhost resolves to the container itself; db is registered as an A record by the embedded DNS server. There is no links: block, no /etc/hosts editing, and no need to run Consul or etcd for a local dev stack. Scale a service to multiple replicas and the same hostname round-robins across them.

To see the records at runtime:

docker compose exec app nslookup db
docker compose exec app getent hosts redis

If a hostname fails to resolve, the two services are almost certainly on different networks. Check with docker network inspect <project>_backend and move the service onto the right one, or add an explicit networks: block so the dependency is visible in the file rather than implicit.

Volumes & Environment Variables — Persist Data and Config

Docker volumes are the storage primitive that lets a container's filesystem outlive the container itself. A container's writable layer is torn down on rm; a volume is a directory managed by Docker (on the host, in /var/lib/docker/volumes/...) that one or more containers can mount. Volumes are the only safe way to keep database files, uploaded assets, and other state across rebuilds, restarts, and image upgrades.

There are three volume shapes and they behave very differently.

Type	Syntax	Survives `down`?	Use for
Named	`pgdata:/var/lib/postgresql/data`	Yes	Database data, anything persistent
Bind	`./src:/app/src`	Yes (host-owned)	Live source code, hot reload
Anonymous	`/var/lib/postgresql/data` (no name)	No	Almost never — avoid

Anonymous volumes look like a short convenience, but Docker gives them a random hash and drops them when the container goes. That's how I lost a Postgres database in 2017 and learned this lesson.

For environment variables, three patterns work in Compose. A literal block (fine for dev), an .env file (better for secrets), and the host shell (best for CI). For real secrets in production, prefer Docker secrets on Swarm or the orchestrator's secret store — never bake .env into the image.

# docker-compose.override.yml
services:
  app:
    env_file:
      - .env.local
    volumes:
      - ./src:/app/src:ro

The docker-compose.override.yml file is auto-merged with docker-compose.yml when you run docker compose up. Use it for dev-only overrides (bind mounts, dev env vars) and keep the base file clean.

Best Practices — Efficient Images and Caching

The Dockerfile patterns that buy you the most:

Order by change frequency. package.json and lockfile go before source. Source before build. Build output last.
Use --mount=type=cache in BuildKit for package manager caches. For npm, replace RUN npm ci with:

# syntax=docker/dockerfile:1
RUN --mount=type=cache,target=/root/.npm \
    --mount=type=bind,source=package-lock.json,target=package-lock.json \
    --mount=type=bind,source=package.json,target=package.json \
    npm ci

Pin base images by digest. node:20-alpine@sha256:... is reproducible. node:latest is not.
One process per container. Compose can run multiple, but a single container with multiple daemons makes healthchecks and restarts harder.
Use .dockerignore aggressively. Smaller build context = faster docker build, smaller attack surface.

Two more that I learned the hard way. Don't run apt-get upgrade in the Dockerfile — it pulls in unrelated updates and breaks reproducibility. Don't use ADD for local files — it has surprising URL and tar-extraction behavior; COPY is explicit and predictable.

Security — Scan Images and Harden Containers

A 2026-era checklist before pushing an image anywhere public:

Run a vulnerability scanner. Docker Scout ships with Docker Desktop and the docker scout CLI.
Run as non-root via USER in the final stage.
Drop capabilities you don't need.
Pin base images by digest.
Keep secrets out of layers (.env, ARG, baked files).
Use a minimal base — alpine, distroless, or scratch where possible.

Quick scan:

docker scout cves myapp:1.0.0
docker scout recommendations myapp:1.0.0

Quick hardening diff for the runtime stage:

FROM node:20-alpine AS runtime
WORKDIR /app
ENV NODE_ENV=production
COPY --from=deps /app/node_modules ./node_modules
COPY --from=build /app/dist ./dist
RUN addgroup -S app && adduser -S app -G app
USER app
EXPOSE 3000
CMD ["node", "dist/server.js"]

If docker scout reports a critical CVE in node:20-alpine, the fix is to bump the base tag (or pin to a newer digest). Don't apt-get upgrade inside the Dockerfile to patch it — rebuild from a patched base image.

Troubleshooting — Common Issues and Fixes

`bind: address already in use`

Another process on the host is using the port you mapped. Find and kill it, or change the host-side mapping in Compose ("8080:3000" instead of "3000:3000").

lsof -i :3000
# or on Windows:
netstat -ano | findstr :3000

`ECONNREFUSED 127.0.0.1:5432`

The app is connecting to localhost, which inside the container is itself. Change the connection string to the service name (db), and make sure both services are on the same Compose network. This exact trap catches everyone running Next.js + Postgres for the first time — I cover the wider Supabase flow in Complete Guide to Building SaaS with Next.js and Supabase.

`no space left on device`

Docker's storage driver ran out of room. Prune:

docker system df
docker system prune -a --volumes

--volumes removes named volumes too — only run it if you're sure you don't need them.

`next dev` is slow or hangs inside the container

Bind-mount the source so file changes reach the container, but exclude node_modules so the host's node_modules don't shadow the container's:

volumes:
  - ./src:/app/src:ro
  - /app/node_modules

The anonymous volume /app/node_modules is intentional — it shadows the bind mount at that path, keeping the in-container node_modules.

Image rebuilds every time even though only one file changed

A file outside .dockerignore (or no .dockerignore at all) is invalidating the layer. Add it and rebuild — the next build should hit the cache for every layer above the changed one.

Sanity-check

After docker compose up -d, run this from the host:

docker compose ps
docker compose logs --tail=50 app
curl -sS -o /dev/null -w "%{http_code}\n" http://localhost:3000
docker stats --no-stream

Expected output:

NAME      SERVICE   STATUS          PORTS
myapp-app-1   app       Up 2 minutes (healthy)   0.0.0.0:3000->3000/tcp
myapp-db-1    db        Up 2 minutes (healthy)   5432/tcp

And curl should print 200. docker stats should show two containers with predictable CPU and memory numbers — if app is at 100% CPU constantly, you probably have a hot-reload loop or a missing dependency that triggers restart.

If you're using Next.js and the image optimization endpoint complains about a hostname not being configured, that's a Next.js-level concern unrelated to Docker — the fix is in Fix next/image Hostname Not Configured in Next.js. Likewise, when the App Router tells you a page couldn't be rendered statically because it uses dynamic server data, the answer isn't Docker — it's Fix Dynamic Server Usage Error in Next.js App Router.

FAQ

Do I need Docker Desktop or can I use the CLI alone?
On macOS and Windows, Docker Desktop gives you the daemon, Compose, BuildKit, and Docker Scout in one install. On Linux, the CLI + Compose plugin + BuildKit from the apt repo is enough. Docker Desktop is optional on Linux but adds a GUI and Kubernetes.

Should I learn Kubernetes if I'm just starting with Docker?
No. Compose is the right tool until you actually have multiple hosts or need auto-scaling. I covered that trade-off in the SaaS guide linked earlier — Compose ships the same artifact to Fly.io, Render, and Railway without rewriting.

Can I use the same docker-compose.yml in CI?
Yes. docker compose build works in CI runners, and the resulting images push straight to a registry. For tests, swap the bind mount for an in-memory fixture and use docker compose run --rm app npm test.

How do I keep my dev stack from drifting from production?
Pin base images by digest, run the same Dockerfile everywhere, and run docker compose up in CI against the same docker-compose.yml. Drift is almost always a missing file in .dockerignore or an unpinned base image.

With a reproducible image, a versioned Compose file, named networks with embedded DNS, and named volumes in place, the stack is ready to push to any registry and redeploy on any platform without rewriting the patterns covered above.

Originally published at https://www.iloveblogs.blog

Supabase Storage: Complete Guide to File Uploads and Management

Mahdi BEN RHOUMA — Tue, 23 Jun 2026 22:00:15 +0000

Supabase Storage: Complete Guide to File Uploads and Management

Supabase Storage provides S3-compatible object storage with built-in CDN, image transformations, and security policies. This guide covers everything from basic uploads to production-ready patterns.

Architecture Overview

Client → Supabase Storage API → S3-Compatible Storage → CDN
   ↓                                                        ↓
Upload                                              Fast Delivery
   ↓                                                        ↓
RLS Policies ← ← ← ← ← ← ← ← ← ← ← ← ← ← ← ← ← ← ← ← ← ←

Setup and Configuration

1. Create Storage Buckets

-- Create a public bucket for avatars
INSERT INTO storage.buckets (id, name, public)
VALUES ('avatars', 'avatars', true);

-- Create a private bucket for documents
INSERT INTO storage.buckets (id, name, public)
VALUES ('documents', 'documents', false);

2. Storage Policies

-- Allow users to upload their own avatar
CREATE POLICY "Users can upload their own avatar"
ON storage.objects FOR INSERT
WITH CHECK (
  bucket_id = 'avatars' AND
  auth.uid()::text = (storage.foldername(name))[1]
);

-- Allow users to read their own avatar
CREATE POLICY "Users can read their own avatar"
ON storage.objects FOR SELECT
USING (
  bucket_id = 'avatars' AND
  auth.uid()::text = (storage.foldername(name))[1]
);

-- Allow users to update their own avatar
CREATE POLICY "Users can update their own avatar"
ON storage.objects FOR UPDATE
USING (
  bucket_id = 'avatars' AND
  auth.uid()::text = (storage.foldername(name))[1]
);

-- Allow users to delete their own avatar
CREATE POLICY "Users can delete their own avatar"
ON storage.objects FOR DELETE
USING (
  bucket_id = 'avatars' AND
  auth.uid()::text = (storage.foldername(name))[1]
);

Basic File Upload

Simple Upload Component

'use client';

import { useState } from 'react';
import { createClientComponentClient } from '@supabase/auth-helpers-nextjs';

export default function FileUpload() {
  const [uploading, setUploading] = useState(false);
  const [fileUrl, setFileUrl] = useState<string | null>(null);
  const supabase = createClientComponentClient();

  const uploadFile = async (event: React.ChangeEvent<HTMLInputElement>) => {
    try {
      setUploading(true);

      if (!event.target.files || event.target.files.length === 0) {
        throw new Error('You must select a file to upload.');
      }

      const file = event.target.files[0];
      const fileExt = file.name.split('.').pop();
      const fileName = `${Math.random()}.${fileExt}`;
      const filePath = `${fileName}`;

      const { error: uploadError } = await supabase.storage
        .from('avatars')
        .upload(filePath, file);

      if (uploadError) {
        throw uploadError;
      }

      // Get public URL
      const { data } = supabase.storage
        .from('avatars')
        .getPublicUrl(filePath);

      setFileUrl(data.publicUrl);
    } catch (error) {
      alert(error.message);
    } finally {
      setUploading(false);
    }
  };

  return (
    <div>
      <input
        type="file"
        onChange={uploadFile}
        disabled={uploading}
      />
      {uploading && <p>Uploading...</p>}
      {fileUrl && (
        <div>
          <p>File uploaded successfully!</p>
          <img src={fileUrl} alt="Uploaded file" />
        </div>
      )}
    </div>
  );
}

Advanced Upload Patterns

1. Avatar Upload with Preview

'use client';

import { useState, useRef } from 'react';
import { createClientComponentClient } from '@supabase/auth-helpers-nextjs';
import Image from 'next/image';

export default function AvatarUpload({ userId, currentAvatar }) {
  const [avatar, setAvatar] = useState(currentAvatar);
  const [uploading, setUploading] = useState(false);
  const [preview, setPreview] = useState<string | null>(null);
  const fileInputRef = useRef<HTMLInputElement>(null);
  const supabase = createClientComponentClient();

  const handleFileSelect = (event: React.ChangeEvent<HTMLInputElement>) => {
    const file = event.target.files?.[0];
    if (!file) return;

    // Validate file type
    if (!file.type.startsWith('image/')) {
      alert('Please select an image file');
      return;
    }

    // Validate file size (max 2MB)
    if (file.size > 2 * 1024 * 1024) {
      alert('File size must be less than 2MB');
      return;
    }

    // Create preview
    const reader = new FileReader();
    reader.onloadend = () => {
      setPreview(reader.result as string);
    };
    reader.readAsDataURL(file);
  };

  const uploadAvatar = async () => {
    try {
      setUploading(true);

      const file = fileInputRef.current?.files?.[0];
      if (!file) return;

      // Delete old avatar if exists
      if (avatar) {
        const oldPath = avatar.split('/').pop();
        await supabase.storage
          .from('avatars')
          .remove([`${userId}/${oldPath}`]);
      }

      // Upload new avatar
      const fileExt = file.name.split('.').pop();
      const fileName = `${Date.now()}.${fileExt}`;
      const filePath = `${userId}/${fileName}`;

      const { error: uploadError } = await supabase.storage
        .from('avatars')
        .upload(filePath, file, {
          cacheControl: '3600',
          upsert: false
        });

      if (uploadError) throw uploadError;

      // Get public URL
      const { data } = supabase.storage
        .from('avatars')
        .getPublicUrl(filePath);

      // Update user profile
      const { error: updateError } = await supabase
        .from('profiles')
        .update({ avatar_url: data.publicUrl })
        .eq('id', userId);

      if (updateError) throw updateError;

      setAvatar(data.publicUrl);
      setPreview(null);
      alert('Avatar updated successfully!');
    } catch (error) {
      alert(error.message);
    } finally {
      setUploading(false);
    }
  };

  return (
    <div className="flex flex-col items-center gap-4">
      <div className="relative w-32 h-32 rounded-full overflow-hidden bg-gray-200">
        {(preview || avatar) && (
          <Image
            src={preview || avatar}
            alt="Avatar"
            fill
            className="object-cover"
          />
        )}
      </div>

      <input
        ref={fileInputRef}
        type="file"
        accept="image/*"
        onChange={handleFileSelect}
        className="hidden"
      />

      <div className="flex gap-2">
        <button
          onClick={() => fileInputRef.current?.click()}
          disabled={uploading}
          className="px-4 py-2 bg-blue-500 text-white rounded hover:bg-blue-600"
        >
          Choose File
        </button>

        {preview && (
          <button
            onClick={uploadAvatar}
            disabled={uploading}
            className="px-4 py-2 bg-green-500 text-white rounded hover:bg-green-600"
          >
            {uploading ? 'Uploading...' : 'Upload'}
          </button>
        )}
      </div>
    </div>
  );
}

2. Drag and Drop Upload

'use client';

import { useState, useCallback } from 'react';
import { createClientComponentClient } from '@supabase/auth-helpers-nextjs';
import { Upload } from 'lucide-react';

export default function DragDropUpload({ userId, onUploadComplete }) {
  const [isDragging, setIsDragging] = useState(false);
  const [uploading, setUploading] = useState(false);
  const [progress, setProgress] = useState(0);
  const supabase = createClientComponentClient();

  const handleDrag = useCallback((e: React.DragEvent) => {
    e.preventDefault();
    e.stopPropagation();
  }, []);

  const handleDragIn = useCallback((e: React.DragEvent) => {
    e.preventDefault();
    e.stopPropagation();
    setIsDragging(true);
  }, []);

  const handleDragOut = useCallback((e: React.DragEvent) => {
    e.preventDefault();
    e.stopPropagation();
    setIsDragging(false);
  }, []);

  const handleDrop = useCallback(async (e: React.DragEvent) => {
    e.preventDefault();
    e.stopPropagation();
    setIsDragging(false);

    const files = Array.from(e.dataTransfer.files);
    await uploadFiles(files);
  }, []);

  const uploadFiles = async (files: File[]) => {
    setUploading(true);
    const uploadedUrls: string[] = [];

    for (let i = 0; i < files.length; i++) {
      const file = files[i];
      const fileExt = file.name.split('.').pop();
      const fileName = `${Date.now()}-${i}.${fileExt}`;
      const filePath = `${userId}/${fileName}`;

      try {
        const { error } = await supabase.storage
          .from('documents')
          .upload(filePath, file, {
            cacheControl: '3600',
            upsert: false
          });

        if (error) throw error;

        const { data } = supabase.storage
          .from('documents')
          .getPublicUrl(filePath);

        uploadedUrls.push(data.publicUrl);
        setProgress(((i + 1) / files.length) * 100);
      } catch (error) {
        console.error('Upload error:', error);
      }
    }

    setUploading(false);
    setProgress(0);
    onUploadComplete(uploadedUrls);
  };

  return (
    <div
      onDragEnter={handleDragIn}
      onDragLeave={handleDragOut}
      onDragOver={handleDrag}
      onDrop={handleDrop}
      className={`
        border-2 border-dashed rounded-lg p-8 text-center
        transition-colors cursor-pointer
        ${isDragging ? 'border-blue-500 bg-blue-50' : 'border-gray-300'}
        ${uploading ? 'opacity-50 pointer-events-none' : ''}
      `}
    >
      <Upload className="w-12 h-12 mx-auto mb-4 text-gray-400" />

      {uploading ? (
        <div>
          <p className="text-gray-600 mb-2">Uploading...</p>
          <div className="w-full bg-gray-200 rounded-full h-2">
            <div
              className="bg-blue-500 h-2 rounded-full transition-all"
              style={{ width: `${progress}%` }}
            />
          </div>
        </div>
      ) : (
        <div>
          <p className="text-gray-600 mb-2">
            Drag and drop files here, or click to select
          </p>
          <p className="text-sm text-gray-400">
            Supports: Images, PDFs, Documents
          </p>
        </div>
      )}
    </div>
  );
}

3. Multiple File Upload with Progress

'use client';

import { useState } from 'react';
import { createClientComponentClient } from '@supabase/auth-helpers-nextjs';
import { X, CheckCircle, AlertCircle } from 'lucide-react';

interface UploadFile {
  file: File;
  progress: number;
  status: 'pending' | 'uploading' | 'success' | 'error';
  url?: string;
  error?: string;
}

export default function MultiFileUpload({ userId }) {
  const [files, setFiles] = useState<UploadFile[]>([]);
  const supabase = createClientComponentClient();

  const handleFileSelect = (e: React.ChangeEvent<HTMLInputElement>) => {
    const selectedFiles = Array.from(e.target.files || []);
    const newFiles: UploadFile[] = selectedFiles.map(file => ({
      file,
      progress: 0,
      status: 'pending'
    }));
    setFiles(prev => [...prev, ...newFiles]);
  };

  const uploadFile = async (index: number) => {
    const fileData = files[index];

    setFiles(prev => prev.map((f, i) => 
      i === index ? { ...f, status: 'uploading' } : f
    ));

    try {
      const file = fileData.file;
      const fileExt = file.name.split('.').pop();
      const fileName = `${Date.now()}-${file.name}`;
      const filePath = `${userId}/${fileName}`;

      // Simulate progress (in real app, use XMLHttpRequest for actual progress)
      const progressInterval = setInterval(() => {
        setFiles(prev => prev.map((f, i) => 
          i === index && f.progress < 90
            ? { ...f, progress: f.progress + 10 }
            : f
        ));
      }, 200);

      const { error } = await supabase.storage
        .from('documents')
        .upload(filePath, file);

      clearInterval(progressInterval);

      if (error) throw error;

      const { data } = supabase.storage
        .from('documents')
        .getPublicUrl(filePath);

      setFiles(prev => prev.map((f, i) => 
        i === index
          ? { ...f, progress: 100, status: 'success', url: data.publicUrl }
          : f
      ));
    } catch (error) {
      setFiles(prev => prev.map((f, i) => 
        i === index
          ? { ...f, status: 'error', error: error.message }
          : f
      ));
    }
  };

  const uploadAll = async () => {
    for (let i = 0; i < files.length; i++) {
      if (files[i].status === 'pending') {
        await uploadFile(i);
      }
    }
  };

  const removeFile = (index: number) => {
    setFiles(prev => prev.filter((_, i) => i !== index));
  };

  return (
    <div className="space-y-4">
      <input
        type="file"
        multiple
        onChange={handleFileSelect}
        className="block w-full text-sm text-gray-500
          file:mr-4 file:py-2 file:px-4
          file:rounded-full file:border-0
          file:text-sm file:font-semibold
          file:bg-blue-50 file:text-blue-700
          hover:file:bg-blue-100"
      />

      {files.length > 0 && (
        <button
          onClick={uploadAll}
          disabled={files.every(f => f.status !== 'pending')}
          className="px-4 py-2 bg-blue-500 text-white rounded hover:bg-blue-600 disabled:opacity-50"
        >
          Upload All
        </button>
      )}

      <div className="space-y-2">
        {files.map((fileData, index) => (
          <div
            key={index}
            className="flex items-center gap-3 p-3 border rounded-lg"
          >
            <div className="flex-1">
              <div className="flex items-center justify-between mb-1">
                <span className="text-sm font-medium">
                  {fileData.file.name}
                </span>
                <button
                  onClick={() => removeFile(index)}
                  className="text-gray-400 hover:text-gray-600"
                >
                  <X className="w-4 h-4" />
                </button>
              </div>

              {fileData.status === 'uploading' && (
                <div className="w-full bg-gray-200 rounded-full h-2">
                  <div
                    className="bg-blue-500 h-2 rounded-full transition-all"
                    style={{ width: `${fileData.progress}%` }}
                  />
                </div>
              )}

              {fileData.status === 'success' && (
                <div className="flex items-center gap-2 text-green-600 text-sm">
                  <CheckCircle className="w-4 h-4" />
                  <span>Uploaded successfully</span>
                </div>
              )}

              {fileData.status === 'error' && (
                <div className="flex items-center gap-2 text-red-600 text-sm">
                  <AlertCircle className="w-4 h-4" />
                  <span>{fileData.error}</span>
                </div>
              )}
            </div>
          </div>
        ))}
      </div>
    </div>
  );
}

Image Optimization

1. Image Transformations

// Get optimized image URL
const getOptimizedImageUrl = (path: string, options: {
  width?: number;
  height?: number;
  quality?: number;
  format?: 'webp' | 'avif';
}) => {
  const { data } = supabase.storage
    .from('images')
    .getPublicUrl(path, {
      transform: {
        width: options.width,
        height: options.height,
        quality: options.quality || 80,
        format: options.format || 'webp'
      }
    });

  return data.publicUrl;
};

// Usage
const thumbnailUrl = getOptimizedImageUrl('user-photo.jpg', {
  width: 200,
  height: 200,
  quality: 75,
  format: 'webp'
});

2. Responsive Images Component

'use client';

import Image from 'next/image';
import { createClientComponentClient } from '@supabase/auth-helpers-nextjs';

interface ResponsiveImageProps {
  path: string;
  alt: string;
  sizes?: string;
}

export default function ResponsiveImage({ 
  path, 
  alt, 
  sizes = '100vw' 
}: ResponsiveImageProps) {
  const supabase = createClientComponentClient();

  const getImageUrl = (width: number) => {
    const { data } = supabase.storage
      .from('images')
      .getPublicUrl(path, {
        transform: {
          width,
          quality: 80,
          format: 'webp'
        }
      });
    return data.publicUrl;
  };

  return (
    <Image
      src={getImageUrl(1200)}
      alt={alt}
      width={1200}
      height={800}
      sizes={sizes}
      srcSet={`
        ${getImageUrl(400)} 400w,
        ${getImageUrl(800)} 800w,
        ${getImageUrl(1200)} 1200w,
        ${getImageUrl(1600)} 1600w
      `}
      className="w-full h-auto"
    />
  );
}

Security Best Practices

1. File Type Validation

const ALLOWED_FILE_TYPES = {
  images: ['image/jpeg', 'image/png', 'image/webp', 'image/gif'],
  documents: ['application/pdf', 'application/msword', 'text/plain'],
  videos: ['video/mp4', 'video/webm']
};

const validateFileType = (file: File, category: keyof typeof ALLOWED_FILE_TYPES) => {
  return ALLOWED_FILE_TYPES[category].includes(file.type);
};

// Usage
if (!validateFileType(file, 'images')) {
  throw new Error('Invalid file type. Only images are allowed.');
}

2. File Size Limits

const MAX_FILE_SIZE = {
  avatar: 2 * 1024 * 1024, // 2MB
  document: 10 * 1024 * 1024, // 10MB
  video: 100 * 1024 * 1024 // 100MB
};

const validateFileSize = (file: File, category: keyof typeof MAX_FILE_SIZE) => {
  return file.size <= MAX_FILE_SIZE[category];
};

3. Secure File Names

const generateSecureFileName = (originalName: string, userId: string) => {
  const ext = originalName.split('.').pop();
  const timestamp = Date.now();
  const random = Math.random().toString(36).substring(7);
  return `${userId}/${timestamp}-${random}.${ext}`;
};

Advanced Patterns

1. Signed URLs for Private Files

// Generate signed URL (expires in 1 hour)
const { data, error } = await supabase.storage
  .from('private-documents')
  .createSignedUrl('document.pdf', 3600);

if (data) {
  console.log('Signed URL:', data.signedUrl);
}

2. Batch Operations

// Delete multiple files
const filesToDelete = ['file1.jpg', 'file2.jpg', 'file3.jpg'];

const { data, error } = await supabase.storage
  .from('images')
  .remove(filesToDelete);

3. Move/Copy Files

// Move file
const { data, error } = await supabase.storage
  .from('images')
  .move('old-path/image.jpg', 'new-path/image.jpg');

// Copy file
const { data, error } = await supabase.storage
  .from('images')
  .copy('source/image.jpg', 'destination/image.jpg');

Production Checklist

[ ] Configure storage policies for all buckets
[ ] Implement file type validation
[ ] Set file size limits
[ ] Use secure file naming
[ ] Enable CDN caching
[ ] Implement image optimization
[ ] Add upload progress indicators
[ ] Handle upload errors gracefully
[ ] Clean up unused files periodically
[ ] Monitor storage usage
[ ] Implement rate limiting
[ ] Add virus scanning for user uploads

Conclusion

Supabase Storage provides a complete solution for file management with built-in security, CDN delivery, and image transformations. Key takeaways:

Always implement RLS policies
Validate file types and sizes
Use image transformations for optimization
Implement proper error handling
Clean up unused files regularly

Related Guides

Last updated: February 19, 2026

Originally published at https://www.iloveblogs.blog

Supabase Realtime: Complete Guide to Building Live Applications

Mahdi BEN RHOUMA — Tue, 23 Jun 2026 22:00:07 +0000

Supabase Realtime: Complete Guide to Building Live Applications

Supabase Realtime enables you to build live, collaborative applications with minimal code. This guide covers everything from basic subscriptions to advanced patterns.

What is Supabase Realtime?

Supabase Realtime is built on top of PostgreSQL's replication functionality and provides three main features:

Postgres Changes - Listen to database changes (INSERT, UPDATE, DELETE)
Presence - Track and sync user state across clients
Broadcast - Send ephemeral messages between clients

Architecture Overview

Client → Supabase Realtime Server → PostgreSQL
   ↓                                      ↓
WebSocket                          Replication Slot
   ↓                                      ↓
Live Updates ← ← ← ← ← ← ← ← ← ← ← ← ← ← ←

Setup and Configuration

1. Enable Realtime on Tables

-- Enable realtime for a table
ALTER TABLE messages REPLICA IDENTITY FULL;

-- Or in Supabase Dashboard:
-- Database → Replication → Enable for specific tables

2. Row Level Security (RLS)

-- Enable RLS
ALTER TABLE messages ENABLE ROW LEVEL SECURITY;

-- Policy for reading messages
CREATE POLICY "Users can read messages in their channels"
ON messages FOR SELECT
USING (
  auth.uid() IN (
    SELECT user_id FROM channel_members 
    WHERE channel_id = messages.channel_id
  )
);

-- Policy for inserting messages
CREATE POLICY "Users can insert messages in their channels"
ON messages FOR INSERT
WITH CHECK (
  auth.uid() IN (
    SELECT user_id FROM channel_members 
    WHERE channel_id = messages.channel_id
  )
);

Postgres Changes: Database Subscriptions

Basic Subscription

import { createClientComponentClient } from '@supabase/auth-helpers-nextjs';
import { useEffect, useState } from 'react';

export default function Messages() {
  const [messages, setMessages] = useState([]);
  const supabase = createClientComponentClient();

  useEffect(() => {
    // Fetch initial data
    const fetchMessages = async () => {
      const { data } = await supabase
        .from('messages')
        .select('*')
        .order('created_at', { ascending: true });

      setMessages(data || []);
    };

    fetchMessages();

    // Subscribe to new messages
    const channel = supabase
      .channel('messages')
      .on(
        'postgres_changes',
        {
          event: 'INSERT',
          schema: 'public',
          table: 'messages'
        },
        (payload) => {
          setMessages(prev => [...prev, payload.new]);
        }
      )
      .subscribe();

    return () => {
      supabase.removeChannel(channel);
    };
  }, [supabase]);

  return (
    <div>
      {messages.map(msg => (
        <div key={msg.id}>{msg.content}</div>
      ))}
    </div>
  );
}

Listen to All Events

const channel = supabase
  .channel('all-changes')
  .on(
    'postgres_changes',
    {
      event: '*', // INSERT, UPDATE, DELETE
      schema: 'public',
      table: 'messages'
    },
    (payload) => {
      console.log('Change received!', payload);

      switch (payload.eventType) {
        case 'INSERT':
          setMessages(prev => [...prev, payload.new]);
          break;
        case 'UPDATE':
          setMessages(prev => 
            prev.map(msg => 
              msg.id === payload.new.id ? payload.new : msg
            )
          );
          break;
        case 'DELETE':
          setMessages(prev => 
            prev.filter(msg => msg.id !== payload.old.id)
          );
          break;
      }
    }
  )
  .subscribe();

Filter by Column Value

// Only listen to messages in a specific channel
const channel = supabase
  .channel('channel-messages')
  .on(
    'postgres_changes',
    {
      event: 'INSERT',
      schema: 'public',
      table: 'messages',
      filter: `channel_id=eq.${channelId}` // Filter by channel
    },
    (payload) => {
      setMessages(prev => [...prev, payload.new]);
    }
  )
  .subscribe();

Presence: Track Online Users

Basic Presence Implementation

'use client';

import { useEffect, useState } from 'react';
import { createClientComponentClient } from '@supabase/auth-helpers-nextjs';

export default function OnlineUsers({ roomId, currentUser }) {
  const [onlineUsers, setOnlineUsers] = useState([]);
  const supabase = createClientComponentClient();

  useEffect(() => {
    const channel = supabase.channel(`room:${roomId}`, {
      config: {
        presence: {
          key: currentUser.id
        }
      }
    });

    // Track presence
    channel
      .on('presence', { event: 'sync' }, () => {
        const state = channel.presenceState();
        const users = Object.values(state).flat();
        setOnlineUsers(users);
      })
      .on('presence', { event: 'join' }, ({ newPresences }) => {
        console.log('User joined:', newPresences);
      })
      .on('presence', { event: 'leave' }, ({ leftPresences }) => {
        console.log('User left:', leftPresences);
      })
      .subscribe(async (status) => {
        if (status === 'SUBSCRIBED') {
          // Track current user
          await channel.track({
            user_id: currentUser.id,
            username: currentUser.username,
            avatar: currentUser.avatar,
            online_at: new Date().toISOString()
          });
        }
      });

    return () => {
      channel.untrack();
      supabase.removeChannel(channel);
    };
  }, [roomId, currentUser, supabase]);

  return (
    <div>
      <h3>Online Users ({onlineUsers.length})</h3>
      <ul>
        {onlineUsers.map(user => (
          <li key={user.user_id}>
            <img src={user.avatar} alt={user.username} />
            {user.username}
          </li>
        ))}
      </ul>
    </div>
  );
}

Typing Indicators

export default function ChatInput({ channelId, currentUser }) {
  const [typingUsers, setTypingUsers] = useState([]);
  const supabase = createClientComponentClient();
  const typingTimeoutRef = useRef(null);

  useEffect(() => {
    const channel = supabase.channel(`typing:${channelId}`);

    channel
      .on('presence', { event: 'sync' }, () => {
        const state = channel.presenceState();
        const typing = Object.values(state)
          .flat()
          .filter(user => user.user_id !== currentUser.id);
        setTypingUsers(typing);
      })
      .subscribe();

    return () => {
      supabase.removeChannel(channel);
    };
  }, [channelId, currentUser, supabase]);

  const handleTyping = async () => {
    const channel = supabase.channel(`typing:${channelId}`);

    // Track typing
    await channel.track({
      user_id: currentUser.id,
      username: currentUser.username,
      typing: true
    });

    // Clear previous timeout
    if (typingTimeoutRef.current) {
      clearTimeout(typingTimeoutRef.current);
    }

    // Stop tracking after 3 seconds
    typingTimeoutRef.current = setTimeout(async () => {
      await channel.untrack();
    }, 3000);
  };

  return (
    <div>
      {typingUsers.length > 0 && (
        <div className="text-sm text-gray-500">
          {typingUsers.map(u => u.username).join(', ')} 
          {typingUsers.length === 1 ? ' is' : ' are'} typing...
        </div>
      )}
      <input
        type="text"
        onChange={handleTyping}
        placeholder="Type a message..."
      />
    </div>
  );
}

Broadcast: Send Ephemeral Messages

Cursor Tracking

export default function CollaborativeCanvas({ documentId }) {
  const [cursors, setCursors] = useState({});
  const supabase = createClientComponentClient();

  useEffect(() => {
    const channel = supabase.channel(`canvas:${documentId}`);

    channel
      .on('broadcast', { event: 'cursor' }, ({ payload }) => {
        setCursors(prev => ({
          ...prev,
          [payload.user_id]: payload
        }));
      })
      .subscribe();

    return () => {
      supabase.removeChannel(channel);
    };
  }, [documentId, supabase]);

  const handleMouseMove = async (e) => {
    const channel = supabase.channel(`canvas:${documentId}`);

    await channel.send({
      type: 'broadcast',
      event: 'cursor',
      payload: {
        user_id: currentUser.id,
        x: e.clientX,
        y: e.clientY,
        username: currentUser.username
      }
    });
  };

  return (
    <div onMouseMove={handleMouseMove}>
      {/* Render other users' cursors */}
      {Object.values(cursors).map(cursor => (
        <div
          key={cursor.user_id}
          style={{
            position: 'absolute',
            left: cursor.x,
            top: cursor.y,
            pointerEvents: 'none'
          }}
        >
          <div className="cursor-pointer">
            {cursor.username}
          </div>
        </div>
      ))}

      {/* Your canvas content */}
    </div>
  );
}

Live Reactions

export default function LiveReactions({ postId }) {
  const [reactions, setReactions] = useState([]);
  const supabase = createClientComponentClient();

  useEffect(() => {
    const channel = supabase.channel(`reactions:${postId}`);

    channel
      .on('broadcast', { event: 'reaction' }, ({ payload }) => {
        // Add reaction with animation
        const id = Math.random();
        setReactions(prev => [...prev, { ...payload, id }]);

        // Remove after animation
        setTimeout(() => {
          setReactions(prev => prev.filter(r => r.id !== id));
        }, 3000);
      })
      .subscribe();

    return () => {
      supabase.removeChannel(channel);
    };
  }, [postId, supabase]);

  const sendReaction = async (emoji) => {
    const channel = supabase.channel(`reactions:${postId}`);

    await channel.send({
      type: 'broadcast',
      event: 'reaction',
      payload: {
        emoji,
        user_id: currentUser.id,
        timestamp: Date.now()
      }
    });
  };

  return (
    <div>
      <div className="reaction-buttons">
        {['❤️', '👍', '🎉', '🔥'].map(emoji => (
          <button key={emoji} onClick={() => sendReaction(emoji)}>
            {emoji}
          </button>
        ))}
      </div>

      <div className="reactions-overlay">
        {reactions.map(reaction => (
          <div
            key={reaction.id}
            className="floating-reaction"
            style={{
              left: `${Math.random() * 100}%`,
              animation: 'float-up 3s ease-out'
            }}
          >
            {reaction.emoji}
          </div>
        ))}
      </div>
    </div>
  );
}

Real-World Patterns

1. Chat Application

// components/Chat.tsx
'use client';

import { useEffect, useState, useRef } from 'react';
import { createClientComponentClient } from '@supabase/auth-helpers-nextjs';

interface Message {
  id: string;
  content: string;
  user_id: string;
  username: string;
  created_at: string;
}

export default function Chat({ channelId, currentUser }) {
  const [messages, setMessages] = useState<Message[]>([]);
  const [newMessage, setNewMessage] = useState('');
  const [onlineUsers, setOnlineUsers] = useState([]);
  const messagesEndRef = useRef<HTMLDivElement>(null);
  const supabase = createClientComponentClient();

  useEffect(() => {
    // Fetch initial messages
    const fetchMessages = async () => {
      const { data } = await supabase
        .from('messages')
        .select('*')
        .eq('channel_id', channelId)
        .order('created_at', { ascending: true })
        .limit(50);

      setMessages(data || []);
    };

    fetchMessages();

    // Setup realtime channel
    const channel = supabase.channel(`chat:${channelId}`, {
      config: {
        presence: { key: currentUser.id }
      }
    });

    // Listen to new messages
    channel
      .on(
        'postgres_changes',
        {
          event: 'INSERT',
          schema: 'public',
          table: 'messages',
          filter: `channel_id=eq.${channelId}`
        },
        (payload) => {
          setMessages(prev => [...prev, payload.new as Message]);
          scrollToBottom();
        }
      )
      // Track online users
      .on('presence', { event: 'sync' }, () => {
        const state = channel.presenceState();
        setOnlineUsers(Object.values(state).flat());
      })
      .subscribe(async (status) => {
        if (status === 'SUBSCRIBED') {
          await channel.track({
            user_id: currentUser.id,
            username: currentUser.username,
            online_at: new Date().toISOString()
          });
        }
      });

    return () => {
      channel.untrack();
      supabase.removeChannel(channel);
    };
  }, [channelId, currentUser, supabase]);

  const scrollToBottom = () => {
    messagesEndRef.current?.scrollIntoView({ behavior: 'smooth' });
  };

  const sendMessage = async (e: React.FormEvent) => {
    e.preventDefault();
    if (!newMessage.trim()) return;

    await supabase.from('messages').insert({
      content: newMessage,
      channel_id: channelId,
      user_id: currentUser.id,
      username: currentUser.username
    });

    setNewMessage('');
  };

  return (
    <div className="flex flex-col h-screen">
      {/* Online users */}
      <div className="p-4 border-b">
        <span className="text-sm text-gray-600">
          {onlineUsers.length} online
        </span>
      </div>

      {/* Messages */}
      <div className="flex-1 overflow-y-auto p-4">
        {messages.map(msg => (
          <div
            key={msg.id}
            className={`mb-4 ${
              msg.user_id === currentUser.id ? 'text-right' : ''
            }`}
          >
            <div className="text-sm text-gray-600">{msg.username}</div>
            <div
              className={`inline-block p-3 rounded-lg ${
                msg.user_id === currentUser.id
                  ? 'bg-blue-500 text-white'
                  : 'bg-gray-200'
              }`}
            >
              {msg.content}
            </div>
          </div>
        ))}
        <div ref={messagesEndRef} />
      </div>

      {/* Input */}
      <form onSubmit={sendMessage} className="p-4 border-t">
        <input
          type="text"
          value={newMessage}
          onChange={(e) => setNewMessage(e.target.value)}
          placeholder="Type a message..."
          className="w-full p-2 border rounded"
        />
      </form>
    </div>
  );
}

2. Live Notifications

// components/NotificationBell.tsx
'use client';

import { useEffect, useState } from 'react';
import { createClientComponentClient } from '@supabase/auth-helpers-nextjs';
import { Bell } from 'lucide-react';

export default function NotificationBell({ userId }) {
  const [unreadCount, setUnreadCount] = useState(0);
  const [notifications, setNotifications] = useState([]);
  const [isOpen, setIsOpen] = useState(false);
  const supabase = createClientComponentClient();

  useEffect(() => {
    // Fetch initial unread count
    const fetchUnreadCount = async () => {
      const { count } = await supabase
        .from('notifications')
        .select('*', { count: 'exact', head: true })
        .eq('user_id', userId)
        .eq('read', false);

      setUnreadCount(count || 0);
    };

    fetchUnreadCount();

    // Subscribe to new notifications
    const channel = supabase
      .channel('notifications')
      .on(
        'postgres_changes',
        {
          event: 'INSERT',
          schema: 'public',
          table: 'notifications',
          filter: `user_id=eq.${userId}`
        },
        (payload) => {
          setUnreadCount(prev => prev + 1);
          setNotifications(prev => [payload.new, ...prev]);

          // Show browser notification
          if ('Notification' in window && Notification.permission === 'granted') {
            new Notification(payload.new.title, {
              body: payload.new.message,
              icon: '/icon.png'
            });
          }
        }
      )
      .subscribe();

    return () => {
      supabase.removeChannel(channel);
    };
  }, [userId, supabase]);

  const markAsRead = async (notificationId) => {
    await supabase
      .from('notifications')
      .update({ read: true })
      .eq('id', notificationId);

    setUnreadCount(prev => Math.max(0, prev - 1));
  };

  return (
    <div className="relative">
      <button
        onClick={() => setIsOpen(!isOpen)}
        className="relative p-2"
      >
        <Bell className="w-6 h-6" />
        {unreadCount > 0 && (
          <span className="absolute top-0 right-0 bg-red-500 text-white text-xs rounded-full w-5 h-5 flex items-center justify-center">
            {unreadCount}
          </span>
        )}
      </button>

      {isOpen && (
        <div className="absolute right-0 mt-2 w-80 bg-white rounded-lg shadow-lg border">
          <div className="p-4 border-b">
            <h3 className="font-semibold">Notifications</h3>
          </div>
          <div className="max-h-96 overflow-y-auto">
            {notifications.map(notif => (
              <div
                key={notif.id}
                className={`p-4 border-b hover:bg-gray-50 cursor-pointer ${
                  !notif.read ? 'bg-blue-50' : ''
                }`}
                onClick={() => markAsRead(notif.id)}
              >
                <div className="font-medium">{notif.title}</div>
                <div className="text-sm text-gray-600">{notif.message}</div>
              </div>
            ))}
          </div>
        </div>
      )}
    </div>
  );
}

3. Collaborative Document Editing

// components/CollaborativeEditor.tsx
'use client';

import { useEffect, useState, useRef } from 'react';
import { createClientComponentClient } from '@supabase/auth-helpers-nextjs';

export default function CollaborativeEditor({ documentId, currentUser }) {
  const [content, setContent] = useState('');
  const [cursors, setCursors] = useState({});
  const [selections, setSelections] = useState({});
  const editorRef = useRef<HTMLTextAreaElement>(null);
  const supabase = createClientComponentClient();

  useEffect(() => {
    // Fetch document
    const fetchDocument = async () => {
      const { data } = await supabase
        .from('documents')
        .select('content')
        .eq('id', documentId)
        .single();

      setContent(data?.content || '');
    };

    fetchDocument();

    const channel = supabase.channel(`doc:${documentId}`, {
      config: {
        presence: { key: currentUser.id }
      }
    });

    channel
      // Listen to content changes
      .on(
        'postgres_changes',
        {
          event: 'UPDATE',
          schema: 'public',
          table: 'documents',
          filter: `id=eq.${documentId}`
        },
        (payload) => {
          setContent(payload.new.content);
        }
      )
      // Track user presence
      .on('presence', { event: 'sync' }, () => {
        const state = channel.presenceState();
        const users = Object.values(state).flat();

        const newCursors = {};
        const newSelections = {};

        users.forEach(user => {
          if (user.user_id !== currentUser.id) {
            newCursors[user.user_id] = user.cursor;
            newSelections[user.user_id] = user.selection;
          }
        });

        setCursors(newCursors);
        setSelections(newSelections);
      })
      // Listen to cursor movements
      .on('broadcast', { event: 'cursor' }, ({ payload }) => {
        if (payload.user_id !== currentUser.id) {
          setCursors(prev => ({
            ...prev,
            [payload.user_id]: payload.position
          }));
        }
      })
      .subscribe(async (status) => {
        if (status === 'SUBSCRIBED') {
          await channel.track({
            user_id: currentUser.id,
            username: currentUser.username,
            color: currentUser.color
          });
        }
      });

    return () => {
      channel.untrack();
      supabase.removeChannel(channel);
    };
  }, [documentId, currentUser, supabase]);

  const handleChange = async (e) => {
    const newContent = e.target.value;
    setContent(newContent);

    // Debounced save
    clearTimeout(window.saveTimeout);
    window.saveTimeout = setTimeout(async () => {
      await supabase
        .from('documents')
        .update({ content: newContent })
        .eq('id', documentId);
    }, 1000);
  };

  const handleSelectionChange = async () => {
    const channel = supabase.channel(`doc:${documentId}`);
    const start = editorRef.current?.selectionStart;
    const end = editorRef.current?.selectionEnd;

    await channel.send({
      type: 'broadcast',
      event: 'cursor',
      payload: {
        user_id: currentUser.id,
        position: start,
        selection: { start, end }
      }
    });
  };

  return (
    <div className="relative">
      <textarea
        ref={editorRef}
        value={content}
        onChange={handleChange}
        onSelect={handleSelectionChange}
        className="w-full h-screen p-4 font-mono"
      />

      {/* Show other users' cursors */}
      {Object.entries(cursors).map(([userId, position]) => (
        <div
          key={userId}
          className="absolute w-0.5 h-6 bg-blue-500"
          style={{
            top: `${Math.floor(position / 80) * 24}px`,
            left: `${(position % 80) * 9}px`
          }}
        />
      ))}
    </div>
  );
}

Performance Optimization

1. Channel Multiplexing

// Reuse the same channel for multiple subscriptions
const channel = supabase.channel('room-1');

channel
  .on('postgres_changes', { event: 'INSERT', schema: 'public', table: 'messages' }, handleMessage)
  .on('postgres_changes', { event: 'INSERT', schema: 'public', table: 'reactions' }, handleReaction)
  .on('presence', { event: 'sync' }, handlePresence)
  .on('broadcast', { event: 'cursor' }, handleCursor)
  .subscribe();

2. Throttling Updates

import { throttle } from 'lodash';

const sendCursorUpdate = throttle(async (x, y) => {
  await channel.send({
    type: 'broadcast',
    event: 'cursor',
    payload: { x, y }
  });
}, 100); // Max 10 updates per second

3. Cleanup and Memory Management

useEffect(() => {
  const channel = supabase.channel('my-channel');

  // ... setup subscriptions

  return () => {
    // Always cleanup
    channel.untrack();
    supabase.removeChannel(channel);
  };
}, [dependencies]);

Troubleshooting

Common Issues

Not receiving updates
- Check RLS policies
- Verify table has REPLICA IDENTITY FULL
- Ensure channel is subscribed
Too many connections
- Reuse channels when possible
- Implement connection pooling
- Use channel multiplexing
Delayed updates
- Check network latency
- Optimize database queries
- Use broadcast for ephemeral data

Best Practices

Always cleanup subscriptions in useEffect return
Use RLS policies to secure realtime data
Throttle frequent updates (cursor movements, typing)
Handle reconnection gracefully
Test with multiple clients to catch race conditions
Monitor channel status and show connection state to users

Conclusion

Supabase Realtime makes building live, collaborative features straightforward. Key takeaways:

Use Postgres Changes for database updates
Use Presence for user state tracking
Use Broadcast for ephemeral messages
Always implement proper RLS policies
Clean up subscriptions to prevent memory leaks

Related Guides

Last updated: February 19, 2026

Originally published at https://www.iloveblogs.blog

Why Developers Are Switching from Firebase to Supabase (And You Should Too)

Mahdi BEN RHOUMA — Mon, 22 Jun 2026 15:03:06 +0000

Why Developers Are Switching from Firebase to Supabase (And You Should Too)

Something shifted in the developer world.

Firebase used to be the default answer to "what backend should I use?" For years, it was the obvious choice — fast setup, real-time database, free tier, backed by Google. Done.

But scroll through any developer community in 2026 — Reddit, X, Discord, Hacker News — and you will see the same pattern: developers are leaving Firebase for Supabase. Not just a few. Thousands.

This is not hype. There are real, practical reasons driving this migration. And if you are still on Firebase, this article will show you exactly why the switch is happening — and how to do it yourself.

The 4 Reasons Developers Are Leaving Firebase

1. The Pricing Time Bomb

This is the number one reason. Every Firebase developer has a horror story.

Firebase charges per document read and write. Sounds fine until your app gets traffic:

Small app (1,000 users):
├── 500K Firestore reads/month  → $0.30
├── 100K Firestore writes/month → $0.18
└── Total: ~$0.50/month         → Feels free!

Growing app (50,000 users):
├── 50M Firestore reads/month   → $30
├── 10M Firestore writes/month  → $18
├── Cloud Functions              → $15
└── Total: ~$63/month           → Getting expensive

Popular app (500,000 users):
├── 500M Firestore reads/month  → $300
├── 100M Firestore writes/month → $180
├── Cloud Functions              → $80
├── Bandwidth                    → $50
└── Total: ~$610/month          → WHERE DID THIS COME FROM?

The problem is not just the cost — it's the unpredictability. A single viral moment, a bot scraping your app, or a poorly optimized query can spike your bill overnight.

Real story: A developer shipped a dashboard that fetched 100 Firestore documents on page load. With 10,000 daily active users, that is 1 million reads per day — 30 million per month — just from one page. The monthly bill jumped from $15 to $180 overnight.

Supabase pricing is flat. $25/month for Pro. Your app can make a billion queries — the price stays the same. You pay for compute and storage, not for how many times your users press a button.

2. NoSQL Hit a Wall

Firestore seemed great when your app was simple. But then you needed to:

Show a leaderboard → No ORDER BY with LIMIT across collections
Count total users → No COUNT — you read every document or maintain a counter
Join user data with orders → No JOINs — you denormalize or make multiple queries
Search by multiple fields → Requires composite indexes for every combination
Run analytics → Read every document, aggregate client-side

Here is what a simple "top customers" query looks like in both:

Supabase (PostgreSQL):

SELECT
  users.name,
  COUNT(orders.id) as order_count,
  SUM(orders.total) as total_spent
FROM users
JOIN orders ON users.id = orders.user_id
WHERE orders.created_at > NOW() - INTERVAL '30 days'
GROUP BY users.id
ORDER BY total_spent DESC
LIMIT 10;

One query. One database call. Instant.

Firebase (Firestore):

// Step 1: Get all orders from last 30 days
const ordersSnap = await getDocs(
  query(
    collection(db, 'orders'),
    where('createdAt', '>', thirtyDaysAgo)
  )
);

// Step 2: Group by userId (client-side)
const userTotals = {};
ordersSnap.forEach(doc => {
  const order = doc.data();
  if (!userTotals[order.userId]) {
    userTotals[order.userId] = { count: 0, total: 0 };
  }
  userTotals[order.userId].count++;
  userTotals[order.userId].total += order.total;
});

// Step 3: Sort client-side
const topCustomers = Object.entries(userTotals)
  .sort(([, a], [, b]) => b.total - a.total)
  .slice(0, 10);

// Step 4: Fetch each user's name (N more reads!)
const results = await Promise.all(
  topCustomers.map(async ([userId, stats]) => {
    const userDoc = await getDoc(doc(db, 'users', userId));
    return { name: userDoc.data().name, ...stats };
  })
);

That is potentially thousands of document reads for something PostgreSQL does in one query. And you are paying for every single read.

3. Vendor Lock-In Is Real

With Firebase:

Your data is in Firestore (proprietary NoSQL format)
Your auth is in Firebase Auth (Google-only)
Your functions are Cloud Functions (Google Cloud)
You cannot self-host any of it
Exporting data means manually converting documents to another format

If Google changes pricing, deprecates a feature, or you just want to move — you are rewriting your entire backend.

With Supabase:

Your data is in PostgreSQL — the industry standard
Export with pg_dump, import anywhere
Fully open-source — self-host with Docker
Zero proprietary formats

# Leave Supabase? Take your data with you.
pg_dump -h db.yourproject.supabase.co -U postgres -d postgres > backup.sql

# Restore to any PostgreSQL host
psql -h your-new-host.com -U postgres -d myapp < backup.sql

Supabase is the only major BaaS that is fully open-source. If Supabase disappeared tomorrow, you could self-host everything with Docker and keep building. Try doing that with Firebase.

4. Server-Side Rendering Changed Everything

Firebase was built for a world of client-side SPAs — single-page applications where JavaScript runs in the browser.

But the web moved on. Next.js App Router, Server Components, Server Actions — the future is server-first. And Firebase does not fit.

The Firebase problem with Next.js:

// You need TWO different Firebase SDKs
import { getFirestore } from 'firebase/firestore'        // Client
import { getFirestore } from 'firebase-admin/firestore'  // Server

// Different APIs, different auth contexts, different behavior
// Client SDK uses user tokens, Admin SDK bypasses security rules
// You constantly context-switch between two mental models

Supabase with Next.js:

// One API, works everywhere
import { createClient } from '@/lib/supabase/server'

// Server Component
export default async function Page() {
  const supabase = await createClient()
  const { data } = await supabase.from('posts').select('*')
  return <PostList posts={data} />
}

// Server Action
export async function createPost(formData: FormData) {
  const supabase = await createClient()
  await supabase.from('posts').insert({ title: formData.get('title') })
  revalidatePath('/posts')
}

Same client, same API, same mental model. Supabase's @supabase/ssr package was built for the server-first world.

How to Migrate: Step-by-Step

Ready to switch? Here is the practical migration path.

Step 1: Map Your Firestore Collections to PostgreSQL Tables

Firestore documents become rows. Collections become tables. Nested data gets normalized.

Before (Firestore):

users/
  userId1/
    name: "Alice"
    email: "alice@example.com"
    orders/
      orderId1/
        product: "Widget"
        amount: 29.99
        status: "shipped"

After (PostgreSQL):

CREATE TABLE users (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  name TEXT NOT NULL,
  email TEXT UNIQUE NOT NULL,
  created_at TIMESTAMPTZ DEFAULT NOW()
);

CREATE TABLE orders (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  user_id UUID REFERENCES users(id) ON DELETE CASCADE,
  product TEXT NOT NULL,
  amount DECIMAL(10,2) NOT NULL,
  status TEXT DEFAULT 'pending',
  created_at TIMESTAMPTZ DEFAULT NOW()
);

-- Enable RLS
ALTER TABLE users ENABLE ROW LEVEL SECURITY;
ALTER TABLE orders ENABLE ROW LEVEL SECURITY;

CREATE POLICY "Users see own data" ON users
  FOR SELECT USING (auth.uid() = id);

CREATE POLICY "Users see own orders" ON orders
  FOR SELECT USING (auth.uid() = user_id);

Step 2: Migrate Auth Users

Export from Firebase, import to Supabase:

// scripts/migrate-auth.ts
import admin from 'firebase-admin'
import { createClient } from '@supabase/supabase-js'

const firebase = admin.initializeApp({
  credential: admin.credential.cert('./firebase-service-account.json')
})

const supabase = createClient(
  process.env.SUPABASE_URL!,
  process.env.SUPABASE_SERVICE_ROLE_KEY!
)

async function migrateUsers() {
  const listResult = await firebase.auth().listUsers(1000)

  for (const user of listResult.users) {
    const { data, error } = await supabase.auth.admin.createUser({
      email: user.email!,
      email_confirm: true,
      user_metadata: {
        name: user.displayName,
        avatar_url: user.photoURL,
        firebase_uid: user.uid // keep reference
      }
    })

    if (error) {
      console.error(`Failed to migrate ${user.email}:`, error.message)
    } else {
      console.log(`Migrated: ${user.email} → ${data.user.id}`)
    }
  }
}

migrateUsers()

Send your users an email before migration: "We are upgrading our infrastructure. You may need to reset your password on your next login." This covers the password hash issue gracefully.

Step 3: Migrate Data

Export Firestore collections to PostgreSQL:

// scripts/migrate-data.ts
import admin from 'firebase-admin'
import { createClient } from '@supabase/supabase-js'

const db = admin.firestore()
const supabase = createClient(
  process.env.SUPABASE_URL!,
  process.env.SUPABASE_SERVICE_ROLE_KEY!
)

async function migrateCollection(
  collectionName: string,
  tableName: string,
  transform: (doc: any) => any
) {
  const snapshot = await db.collection(collectionName).get()
  const rows = snapshot.docs.map(doc => transform({
    firebase_id: doc.id,
    ...doc.data()
  }))

  // Insert in batches of 500
  for (let i = 0; i < rows.length; i += 500) {
    const batch = rows.slice(i, i + 500)
    const { error } = await supabase.from(tableName).insert(batch)

    if (error) {
      console.error(`Batch ${i} failed:`, error.message)
    } else {
      console.log(`Migrated ${Math.min(i + 500, rows.length)}/${rows.length} ${collectionName}`)
    }
  }
}

// Migrate users first (referenced by other tables)
await migrateCollection('users', 'users', (doc) => ({
  id: doc.firebase_id, // or map to new Supabase auth user ID
  name: doc.name,
  email: doc.email,
  created_at: doc.createdAt?.toDate() || new Date()
}))

// Then migrate orders
await migrateCollection('orders', 'orders', (doc) => ({
  user_id: doc.userId, // map to new user ID
  product: doc.product,
  amount: doc.amount,
  status: doc.status,
  created_at: doc.createdAt?.toDate() || new Date()
}))

Step 4: Update Your App Code

Replace Firebase SDK calls with Supabase equivalents:

// BEFORE: Firebase
import { collection, getDocs, addDoc, query, where } from 'firebase/firestore'

const q = query(collection(db, 'tasks'), where('userId', '==', user.uid))
const snapshot = await getDocs(q)
const tasks = snapshot.docs.map(doc => ({ id: doc.id, ...doc.data() }))

await addDoc(collection(db, 'tasks'), {
  title: 'New task',
  userId: user.uid,
  completed: false
})

// AFTER: Supabase
import { createClient } from '@/lib/supabase/server'

const supabase = await createClient()

// RLS handles the user filtering automatically
const { data: tasks } = await supabase
  .from('tasks')
  .select('*')
  .order('created_at', { ascending: false })

await supabase.from('tasks').insert({
  title: 'New task',
  // user_id is set automatically via RLS + auth.uid()
})

Notice how the Supabase version is shorter? You do not need to filter by user ID — Row Level Security handles it automatically. Less code, fewer bugs.

Step 5: Replace Firebase Services

Firebase Service	Supabase Equivalent
Firestore	PostgreSQL database
Firebase Auth	Supabase Auth
Cloud Storage	Supabase Storage
Cloud Functions	Supabase Edge Functions + Next.js Server Actions
Hosting	Vercel (for Next.js)
Realtime Database	Supabase Realtime
Analytics	PostHog or Plausible
Crashlytics	Sentry
Cloud Messaging	OneSignal or Novu

Migration Timeline

For a typical mid-size app:

Week 1:
├── Day 1-2: Set up Supabase project, design PostgreSQL schema
├── Day 3-4: Migrate auth users
└── Day 5: Migrate data

Week 2:
├── Day 1-3: Update app code (replace Firebase SDK with Supabase)
├── Day 4: Test everything
└── Day 5: Deploy + monitor

You do not have to migrate everything at once. Start with new features on Supabase. Migrate existing features one at a time. Run both in parallel until you are confident.

The Results After Switching

Developers who migrated report:

60-80% lower monthly costs — flat pricing vs per-read billing
Faster development — SQL queries replace complex NoSQL workarounds
Better Next.js integration — first-party SSR support, Server Actions
Simpler codebase — one API everywhere, RLS handles authorization
Peace of mind — open source, no vendor lock-in, data portability

Should You Switch?

Switch now if:

Your Firebase bill is growing faster than your revenue
You are fighting Firestore's query limitations
You are building with Next.js (App Router)
You want data ownership and portability
You are starting a new project

Stay on Firebase if:

Your app is deeply integrated with Google Cloud services
You rely heavily on Firebase Cloud Messaging for push notifications
Your team has deep Firebase expertise and no SQL experience
Your app is small, stable, and Firebase costs are negligible

For everyone else — especially if you are building with Next.js — the switch to Supabase is one of the best decisions you will make in 2026.

Ready to start building? Check out our step-by-step tutorial to build a full-stack app with Next.js and Supabase — you will have a working app in 20 minutes.

Related:

Originally published at https://www.iloveblogs.blog

WebAssembly vs JavaScript: The Performance Revolution in 2026

Mahdi BEN RHOUMA — Mon, 22 Jun 2026 15:03:03 +0000

WebAssembly vs JavaScript: The Performance Revolution in

WebAssembly promised near-native performance in browsers. Three years later, it's delivering on that promise in ways that are reshaping how we think about web applications. Here's what you need to know about the WASM revolution.

Related reading: Check out our guides on React performance optimization and Docker development setup for more performance insights.

The WebAssembly Reality Check

What WebAssembly Actually Is

Not a replacement for JavaScript: WASM complements JavaScript, handling compute-intensive tasks while JS manages DOM manipulation and application logic.

Near-native performance: WASM runs at 95% of native speed, compared to JavaScript's 10-50% depending on the task.

Language agnostic: Write in C++, Rust, Go, or AssemblyScript and compile to WASM.

Real-World Performance Gains

Image processing: 10-50x faster than JavaScript
Mathematical computations: 5-20x performance improvement
Game engines: 60fps complex 3D rendering in browsers
Cryptography: 3-15x faster encryption/decryption
Audio/video processing: Real-time effects without lag

When to Choose WebAssembly

Perfect Use Cases

CPU-intensive computations:

Image/video processing
Scientific simulations
Cryptographic operations
Game engines
Audio synthesis

Legacy code migration:

Existing C/C++ libraries
Desktop app porting
Performance-critical algorithms
Mathematical libraries

Real-time applications:

Live video streaming
Audio workstations
Trading platforms
Scientific visualization

When to Stick with JavaScript

DOM manipulation: JavaScript is still king for UI interactions
Simple business logic: WASM overhead isn't worth it
Rapid prototyping: JS development is faster
Small applications: Bundle size matters more than performance

Getting Started with WebAssembly

Your First WASM Module

Step 1: Install Emscripten

## Install Emscripten SDK
git clone https://github.com/emscripten-core/emsdk.git
cd emsdk
./emsdk install latest
./emsdk activate latest
source ./emsdk_env.sh

Step 2: Write C++ code

// math.cpp
#include <emscripten/emscripten.h>

extern "C" {
    EMSCRIPTEN_KEEPALIVE
    double fibonacci(int n) {
        if (n <= 1) return n;
        return fibonacci(n - 1) + fibonacci(n - 2);
    }

    EMSCRIPTEN_KEEPALIVE
    void processArray(double* arr, int length) {
        for (int i = 0; i < length; i++) {
            arr[i] = arr[i] * arr[i];
        }
    }
}

Step 3: Compile to WASM

emcc math.cpp -o math.js -s EXPORTED_FUNCTIONS='["_fibonacci", "_processArray"]' -s EXPORTED_RUNTIME_METHODS='["ccall", "cwrap"]'

Step 4: Use in JavaScript

// Load and use WASM module
async function loadWASM() {
    const Module = await import('./math.js');
    await Module.default();

    // Call WASM functions
    const fibonacci = Module.cwrap('fibonacci', 'number', ['number']);
    const result = fibonacci(40);
    console.log('Fibonacci(40):', result);

    // Process arrays
    const processArray = Module.cwrap('processArray', null, ['number', 'number']);
    const data = new Float64Array([1, 2, 3, 4, 5]);
    const ptr = Module._malloc(data.length * data.BYTES_PER_ELEMENT);
    Module.HEAPF64.set(data, ptr / data.BYTES_PER_ELEMENT);

    processArray(ptr, data.length);

    const result = Module.HEAPF64.subarray(
        ptr / data.BYTES_PER_ELEMENT,
        ptr / data.BYTES_PER_ELEMENT + data.length
    );
    console.log('Processed array:', Array.from(result));

    Module._free(ptr);
}

loadWASM();

Rust to WebAssembly

Why Rust + WASM is Powerful

Memory safety: No segfaults or buffer overflows
Performance: Zero-cost abstractions
Tooling: Excellent WASM support with wasm-pack
Ecosystem: Growing collection of WASM-ready crates

Building with Rust

Step 1: Setup

## Install Rust and wasm-pack
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
cargo install wasm-pack

Step 2: Create Rust project

## Cargo.toml
[package]
name = "image-processor"
version = "0.1.0"
edition = "2021"

[lib]
crate-type = ["cdylib"]

[dependencies]
wasm-bindgen = "0.2"
js-sys = "0.3"
web-sys = "0.3"

[dependencies.web-sys]
version = "0.3"
features = [
  "console",
  "ImageData",
  "CanvasRenderingContext2d",
]

Step 3: Write Rust code

// src/lib.rs
use wasm_bindgen::prelude::*;
use web_sys::console;

#[wasm_bindgen]
extern "C" {
    fn alert(s: &str);
}

#[wasm_bindgen]
pub fn greet(name: &str) {
    alert(&format!("Hello, {}!", name));
}

#[wasm_bindgen]
pub struct ImageProcessor {
    width: u32,
    height: u32,
    data: Vec<u8>,
}

#[wasm_bindgen]
impl ImageProcessor {
    #[wasm_bindgen(constructor)]
    pub fn new(width: u32, height: u32) -> ImageProcessor {
        ImageProcessor {
            width,
            height,
            data: vec![0; (width * height * 4) as usize],
        }
    }

    #[wasm_bindgen]
    pub fn apply_grayscale(&mut self) {
        for i in (0..self.data.len()).step_by(4) {
            let r = self.data[i] as f32;
            let g = self.data[i + 1] as f32;
            let b = self.data[i + 2] as f32;

            let gray = (0.299 * r + 0.587 * g + 0.114 * b) as u8;

            self.data[i] = gray;
            self.data[i + 1] = gray;
            self.data[i + 2] = gray;
        }
    }

    #[wasm_bindgen]
    pub fn get_data(&self) -> Vec<u8> {
        self.data.clone()
    }
}

Step 4: Build and use

## Build WASM package
wasm-pack build --target web

## Use in JavaScript
import init, { ImageProcessor, greet } from './pkg/image_processor.js';

async function run() {
    await init();

    greet('WebAssembly');

    const processor = new ImageProcessor(800, 600);
    processor.apply_grayscale();
    const processedData = processor.get_data();
}

run();

Performance Benchmarks

Real-World Comparisons

Image Processing (1920x1080 image):

JavaScript: 450ms
WebAssembly (C++): 45ms
WebAssembly (Rust): 42ms
Winner: WASM (10x faster)

Mathematical Computation (Prime calculation):

JavaScript: 2.3s
WebAssembly: 0.4s
Winner: WASM (5.7x faster)

JSON Parsing (Large dataset):

JavaScript: 120ms
WebAssembly: 180ms
Winner: JavaScript (WASM overhead)

DOM Manipulation:

JavaScript: 50ms
WebAssembly: Not applicable
Winner: JavaScript (only option)

Memory Usage Comparison

JavaScript:

Garbage collection overhead
Dynamic typing memory cost
V8 optimization memory

WebAssembly:

Linear memory model
Manual memory management
Predictable memory usage
Smaller runtime footprint

Advanced WebAssembly Patterns

WASM + Web Workers

// worker.js
importScripts('./math.js');

let wasmModule;

self.onmessage = async function(e) {
    if (!wasmModule) {
        wasmModule = await Module();
    }

    const { operation, data } = e.data;

    switch (operation) {
        case 'processImage':
            const result = wasmModule.processImage(data);
            self.postMessage({ result });
            break;
        case 'calculatePrimes':
            const primes = wasmModule.calculatePrimes(data.limit);
            self.postMessage({ primes });
            break;
    }
};

// main.js
const worker = new Worker('worker.js');

worker.postMessage({
    operation: 'processImage',
    data: imageData
});

worker.onmessage = function(e) {
    console.log('WASM result:', e.data.result);
};

Streaming WASM Compilation

// Optimize loading with streaming
async function loadWASMStreaming(url) {
    const response = await fetch(url);
    const module = await WebAssembly.compileStreaming(response);
    const instance = await WebAssembly.instantiate(module);
    return instance.exports;
}

// Use with caching
const wasmCache = new Map();

async function getWASMModule(name, url) {
    if (wasmCache.has(name)) {
        return wasmCache.get(name);
    }

    const module = await loadWASMStreaming(url);
    wasmCache.set(name, module);
    return module;
}

WASM + TypeScript Integration

// types.d.ts
declare module '*.wasm' {
    const content: WebAssembly.Module;
    export default content;
}

interface WASMExports {
    fibonacci(n: number): number;
    processArray(ptr: number, length: number): void;
    memory: WebAssembly.Memory;
    malloc(size: number): number;
    free(ptr: number): void;
}

// wasm-loader.ts
export class WASMLoader {
    private module: WASMExports | null = null;

    async load(wasmUrl: string): Promise<WASMExports> {
        if (this.module) return this.module;

        const response = await fetch(wasmUrl);
        const wasmModule = await WebAssembly.compileStreaming(response);
        const instance = await WebAssembly.instantiate(wasmModule);

        this.module = instance.exports as WASMExports;
        return this.module;
    }

    processTypedArray(data: Float64Array): Float64Array {
        if (!this.module) throw new Error('WASM not loaded');

        const ptr = this.module.malloc(data.length * 8);
        const heap = new Float64Array(
            this.module.memory.buffer,
            ptr,
            data.length
        );

        heap.set(data);
        this.module.processArray(ptr, data.length);

        const result = new Float64Array(heap);
        this.module.free(ptr);

        return result;
    }
}

WebAssembly in Production

Success Stories

Figma: Uses WASM for their C++ rendering engine, achieving 3x performance improvement over pure JavaScript.

Google Earth: Ported their C++ codebase to WASM, enabling complex 3D rendering in browsers.

AutoCAD Web: Runs full CAD software in browsers using WASM, with performance comparable to desktop apps.

Photoshop Web: Adobe uses WASM for image processing algorithms, delivering professional-grade performance.

Production Considerations

Bundle size: WASM modules can be large (1-10MB+)
Loading time: Initial compilation takes time
Browser support: 95%+ modern browser support
Debugging: Limited debugging tools compared to JavaScript
Memory management: Manual memory management required

Optimization Strategies

Code splitting:

// Load WASM modules on demand
const loadImageProcessor = () => import('./image-processor.wasm');
const loadAudioProcessor = () => import('./audio-processor.wasm');

// Use based on feature detection
if (userWantsImageEditing) {
    const processor = await loadImageProcessor();
    // Use image processor
}

Caching strategies:

// Service worker caching
self.addEventListener('fetch', event => {
    if (event.request.url.endsWith('.wasm')) {
        event.respondWith(
            caches.open('wasm-cache').then(cache => {
                return cache.match(event.request).then(response => {
                    return response || fetch(event.request).then(fetchResponse => {
                        cache.put(event.request, fetchResponse.clone());
                        return fetchResponse;
                    });
                });
            })
        );
    }
});

The Future of WebAssembly

Upcoming Features

WASI (WebAssembly System Interface): Run WASM outside browsers
Garbage Collection: Automatic memory management
Exception Handling: Better error handling
Threads: Multi-threading support
SIMD: Single Instruction, Multiple Data operations

Integration Trends

Framework integration: React, Vue, and Angular adding WASM support
Build tool support: Webpack, Vite, and Rollup improving WASM handling
Language support: More languages targeting WASM
Tooling improvements: Better debugging and profiling tools

Frequently Asked Questions

Q: Should I rewrite my entire app in WebAssembly?
A: No. Use WASM for compute-intensive parts while keeping JavaScript for UI and application logic. A hybrid approach works best.

Q: Is WebAssembly secure?
A: Yes. WASM runs in a sandboxed environment with the same security model as JavaScript. It can't access the DOM directly or make network requests without going through JavaScript.

Q: How much performance improvement can I expect?
A: It depends on the use case. CPU-intensive tasks see 5-50x improvements, while I/O-bound operations see minimal gains. Profile your specific use case.

Q: What about bundle size?
A: WASM modules can be large (1-10MB+), but they compress well with gzip/brotli. Consider the performance vs. size tradeoff for your use case.

Q: Can I debug WebAssembly code?
A: Yes, but tooling is limited. Chrome DevTools supports WASM debugging, and source maps can map back to original C++/Rust code.

WebAssembly is transforming web performance, but it's not a silver bullet. Use it strategically for compute-intensive tasks while leveraging JavaScript's strengths for everything else. The future of web development is hybrid, and WASM is a powerful tool in that toolkit.

Explore more articles in our Next.js Performance series:

Next.js Performance Optimization for Indie Developers - Complete guide covering all aspects
More related articles coming soon

Originally published at https://www.iloveblogs.blog

DEV Community: Mahdi BEN RHOUMA

Supabase redirectTo not working on Vercel previews: SITE_URL fix

How Supabase redirect URLs work

The dashboard config

The environment variable pattern for Vercel

Email templates: the hidden SITE_URL problem

The trailing slash trap

When the fix is not just a URL allowlist

Checklist

Related

Supabase getClaims() vs getSession() in server code: the silent auth bug

What the Supabase docs actually say

The three auth functions and when to use each

getClaims() — for auth checks in server code

getUser() — when you need the freshest user record

getSession() — only safe on the client

The correct pattern for server-side auth

The CDN / ISR cache leak

When getClaims() is not enough

Next.js proxy.js matcher not working: static assets and auth gaps

What changed in Next.js 16

The matcher problem

The auth gap you probably missed: Server Functions

Checklist after migration

When this fix is not the right fix

Related

Missing Suspense boundary with useSearchParams in Next.js: 3 fixes

Why this happens

Fix 1 — Wrap in Suspense (fastest)

Dashboard

Fix 2 — Use the searchParams page prop (recommended for Server Components)

Dashboard

Fix 3 — Force dynamic rendering with connection()

Dashboard

VERCEL_EXPERIMENTAL_DEV_SKIP_LINK: Stop Dev Link Hangs

TL;DR

What VERCEL_EXPERIMENTAL_DEV_SKIP_LINK actually does

How the Vercel dev link works

When to use VERCEL_EXPERIMENTAL_DEV_SKIP_LINK

How it fits into the local dev stack

Before you set it

Setting up the environment variable

Configuration examples

Restarting the development server

Check it worked

Common mistakes and how to avoid them

Troubleshooting connection issues

Debugging when the skip link isn't working

Local development optimization

Best practices for local development

FAQ

Related

JSX.Element vs ReactNode vs ReactElement: TS2322 Fix

TL;DR

The error

Why JSX.Element is too narrow

The switch

Step by step

Component props

Function return types

Check it

Variant A — Using ReactElement instead of ReactNode

Variant B — Strict JSX mode in Next.js or Vite

Going forward

FAQ

What’s the difference between JSX.Element and ReactElement in practice?

When should I use ReactNode instead of JSX.Element as a return type?

How should I type component props in TypeScript React components?

What is the best function return type for React components in TypeScript?

How do I fix 'Type is not assignable to type JSX.Element' errors?

What return type should I use for components that might return null?

How do I properly type children props in React components?

Related

TypeScript Getter Setter Errors: TS1056, TS1028, TS2378 Fix

The errors

Why it happens

The fix — bump your ES target

Step by step

Check it

Variant A — Getter returns undefined or void

Variant A — Using `ReactElement` instead of `ReactNode`

Variant A — Getter returns `undefined` or `void`

`bind: address already in use`

`ECONNREFUSED 127.0.0.1:5432`

`no space left on device`

`next dev` is slow or hangs inside the container