DEV Community: Mahdi BEN RHOUMA

Next.js 16 Removed next lint: ESLint 9 Migration

Mahdi BEN RHOUMA — Sat, 25 Jul 2026 21:47:02 +0000

What actually broke in Next.js 16

Three things disappeared at once, and each one silently changes how your
project behaves in CI:

next lint is removed. Running npx next lint in Next.js 16 throws Unknown command: lint. If your package.json has "lint": "next lint", that script is now dead.
The eslint next.config key is removed. eslint: { ignoreDuringBuilds: true } in next.config.mjs is silently ignored — and so is eslint: { dirs: ['lib'] }.
next build no longer lints. Pre-16, a production build ran an ESLint pass and could fail the build on lint errors. That pass is gone. A build that used to turn red on a lint error now turns green.

This is a migration, not a regression. The Next.js team moved linting to the
ESLint CLI (or Biome) because next lint was a thin wrapper around ESLint
that lagged behind ESLint releases — the original incompatibility with
ESLint 9 was tracked for months in vercel/next.js#64409 before
being fixed, and the team decided to retire the wrapper entirely in v16.

The upgrade guide is the canonical source for the change; the flat-config
default landed in PR #84874, and the migration codemod shipped in
commit c57fe25.

The 30-second path: run the official codemod

Next.js ships a codemod that does the mechanical part for you. From your
project root:

npx @next/codemod@canary next-lint-to-eslint-cli .

It does four things:

Rewrites package.json scripts. "lint": "next lint" becomes "lint": "eslint ."; --strict maps to --max-warnings 0; --dir / --file flags map to explicit paths.
Creates eslint.config.mjs with the Next.js recommended flat config if you do not have one.
Updates an existing flat config to include the Next.js rules if it does not already.
Installs the dependencies for you: eslint, eslint-config-next, @eslint/eslintrc (the compatibility shim you will need if any plugin in your tree still ships legacy config).

Run it, then run npm run lint once to confirm the output is the same shape
as before. That is the happy path. The rest of this article is the unhappy
path — the parts the codemod cannot fix automatically.

Illustration — not a live capture. Verbatim text sourced from the official Next.js 16 upgrade guide and the @next/codemod README. The orange banner inside the image is the renderer-level "not a live capture" badge.

Writing `eslint.config.mjs` by hand

If the codemod does not cover your setup (monorepo, custom rules, Prettier
chain), here is the minimal flat config that reproduces what
eslint-config-next used to give you in legacy .eslintrc.json:

// eslint.config.mjs
import coreWebVitals from 'eslint-config-next/core-web-vitals'
import typescript from 'eslint-config-next/typescript'

const eslintConfig = [
  ...coreWebVitals,
  ...typescript,
  {
    ignores: [
      '.next/**',
      'out/**',
      'build/**',
      'next-env.d.ts',
      'node_modules/**',
    ],
  },
]

export default eslintConfig

Illustration — not a live capture. Example diff; the wording is quoted from the official Next.js ESLint plugin API reference and the upgrade guide. The orange banner inside the image is the renderer-level "not a live capture" badge.

Two subpath exports matter, both confirmed in PR #84874:

eslint-config-next/core-web-vitals — the core-web-vitals ruleset (the one next lint applied by default).
eslint-config-next/typescript — TypeScript-specific rules; add it only if your project uses TypeScript.

The spread is intentional: each export is an array of config objects, so you
concatenate them into one flat config array. Do not wrap them in
defineConfig([...]) and then nest again — ESLint will warn about
configFactory returning an array.

Why not `defineConfig` and `globalIgnores`

You will see tutorials that import defineConfig and globalIgnores from
eslint/config. That works, but it is sugar over the array form. The
@next/eslint-plugin-next README and the PR both use the plain-array form,
which is what eslint-config-next itself exports. Stick to the plain form
and you will not be surprised when a plugin you add does not understand
defineConfig.

`package.json` scripts that replace `next lint`

The codemod writes these for you, but if you are setting them up manually:

{
  "scripts": {
    "dev": "next dev",
    "build": "npm run lint && next build",
    "start": "next start",
    "lint": "eslint .",
    "lint:fix": "eslint --fix ."
  }
}

Two details that bite people:

--max-warnings 0 replaces --strict. The old next lint --strict flag turned warnings into errors. The ESLint CLI equivalent is eslint . --max-warnings 0. Put it in your lint script if you want CI to fail on warnings.
next build no longer lints, so add lint to the build script if your CI relied on the build to catch lint errors. npm run lint && next build is the cheapest way to preserve the old behavior without a separate CI step.

Migrating from a legacy `.eslintrc.json`

If you had a hand-written .eslintrc.json that extended next/core-web-vitals
and added custom rules, the codemod will not perfectly translate your custom
rules. The ESLint project publishes its own migration tool:

npx @eslint/migrate-config .eslintrc.json

It emits a starter eslint.config.mjs that wraps your old config with
FlatCompat from @eslint/eslintrc. The output looks like this:

// eslint.config.mjs — generated by @eslint/migrate-config
import { FlatCompat } from '@eslint/eslintrc'
import { fileURLToPath } from 'node:url'
import { dirname } from 'node:path'

const __filename = fileURLToPath(import.meta.url)
const __dirname = dirname(__filename)

const compat = new FlatCompat({ baseDirectory: __dirname })

const eslintConfig = [
  ...compat.extends('next/core-web-vitals', 'next/typescript'),
  {
    rules: {
      // your old custom rules land here
      'no-console': 'warn',
    },
  },
]

export default eslintConfig

FlatCompat is the bridge: it lets a flat config consume plugins and
shareable configs that still ship the legacy .eslintrc-style export. Use
it for any third-party plugin that has not migrated yet — for example, many
eslint-plugin-* packages on npm still export a legacy config object. Once
the plugin ships a flat config, you can drop the compat layer and import it
directly.

The `.eslintrc` plugins that have not migrated

This is the part the upgrade guide skips. If your .eslintrc.json extended
plugin:prettier/recommended or any plugin that has not published a flat
config export, ESLint 9 will throw Failed to load config "prettier" at
startup. Two fixes, in order of preference:

Use the plugin's flat config export if it has one. Prettier, for instance, ships eslint-config-prettier/flatconfig since v9.1.0. Import it directly and spread it last in your array.
Wrap with FlatCompat if it does not. compat.extends('plugin:prettier/recommended') still works because @eslint/eslintrc knows how to translate the legacy format.

The codemod installs @eslint/eslintrc for exactly this reason. Keep it in
your devDependencies until every plugin in your tree has migrated; then you
can remove it.

CI/CD: where the silent break lives

This is the highest-impact section. Pre-16, a typical GitHub Actions job
looked like:

- run: npm run build

next build ran ESLint, and a lint error failed the job. Post-16, the same
job is green on the same codebase even if it is full of lint errors,
because next build no longer lints. Your lint coverage silently drops to
zero the day you upgrade.

Fix it by adding an explicit lint step before the build:

jobs:
  ci:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npm run lint
      - run: npm run build

If you have a separate CI workflow that already ran next lint, change the
script call from next lint to eslint .. The Next.js + Supabase CI/CD
production guide
covers the broader workflow, but the one-line change for the lint step is
npx next lint → npx eslint ..

The `ignoreDuringBuilds` trap

A lot of projects had this in next.config.mjs:

const nextConfig = {
  eslint: {
    ignoreDuringBuilds: true,
  },
}

In Next.js 16, the eslint key is removed. The config still loads without
error — Next.js ignores unknown keys — so the file does not break. But the
behavior changes: the key no longer does anything because the build no
longer lints at all. You can leave the block in for a version or two as a
no-op, but the clean move is to delete it and move the ignore list into
eslint.config.mjs:

{
  ignores: ['scripts/**', 'docs/**'],
}

That puts all lint configuration in one place — the ESLint flat config —
instead of split between next.config.mjs and .eslintrc.

Common pitfalls, ranked by how often they bite

1. Unknown command: lint in CI. Your CI script still calls
next lint. Change it to eslint . (or run the codemod, which rewrites the
lint script). This is the single most common upgrade break.

2. Failed to load config "next/core-web-vitals". You copied an old
.eslintrc.json that extends next/core-web-vitals into a Next.js 16
project. The legacy export path is gone. Replace the file with
eslint.config.mjs that imports from eslint-config-next/core-web-vitals.

3. next build is green, lint is broken. You removed the lint step
during the upgrade and never added it back. Add npm run lint to CI before
next build — otherwise lint regressions ship to production undetected.
This is the silent-coverage bug above.

4. TypeScript rules missing. You added eslint-config-next/core-web-vitals
but forgot eslint-config-next/typescript. Your @typescript-eslint rules
disappear and no-unused-vars no longer catches unused TS variables. Add
the TypeScript export to the array.

5. Parsing error: Cannot find module 'next/babel'. This is a
different, older issue — a leftover .babelrc referencing next/babel
while the project uses SWC. It is covered separately in the
next/babel parsing error fix;
do not conflate it with the flat-config migration.

A note on Turbopack

next build --turbopack (the Turbopack bundler) is unrelated to this
change. Turbopack replaces Webpack as the bundler; it does not change how
linting works. If you hit a build error after upgrading and it mentions
Turbopack, it is a bundler issue, not a lint issue — the
Turbopack stuck fix covers that
separately. Do not try to "fix" a Turbopack error by editing your ESLint
config.

Verifying the migration worked

Three checks, in order:

npm run lint runs without ERR_MODULE_NOT_FOUND and without Failed to load config. If either appears, a plugin in your tree still ships legacy config — wrap it with FlatCompat.
npm run build succeeds and the build log does not contain a lint pass. Pre-16, the build log had a "Linting and checking validity of types" step; post-16, that step is absent. That absence is correct.
CI fails on a deliberately introduced lint error. Add const _x = 1 to a file, push, and confirm the CI job fails on the npm run lint step. If it passes, your lint script is still pointing at next lint.

Production recommendations

Pin eslint and eslint-config-next to the same minor version as Next.js. A eslint-config-next major bump can change rule severity without warning; lock the version in package.json.
Run lint:fix in pre-commit, not in CI. CI should run eslint . (read-only) and fail on errors. Auto-fixing in CI hides the signal.
Add eslint . --max-warnings 0 to CI only after you reach zero warnings. Turning warnings into errors before the codebase is clean makes CI red for weeks.
Keep @eslint/eslintrc in devDependencies until every plugin in your tree has a flat-config export. Then remove it — the compat layer is dead weight once you do not need it.
Move all ignore patterns into eslint.config.mjs, not next.config.mjs. One source of truth for lint config is the whole point of the migration.

FAQ

Should I migrate to ESLint 9 or wait for ESLint 10?

Migrate now. ESLint 10 will drop legacy config support entirely; v16 already
defaults to flat config and will not maintain backwards compatibility. The
longer you stay on .eslintrc.*, the more painful the eventual move.

Can I use Biome instead of ESLint in Next.js 16?

Yes. The upgrade guide explicitly mentions Biome as an alternative. Biome
does not consume eslint-config-next rules, so you lose the Next-specific
checks (the no-html-link-for-pages, no-img-element, core-web-vitals
rules). If those matter to you, stay on ESLint.

What about the `eslint-config-next` package — is it deprecated?

No. eslint-config-next is the supported way to get Next.js lint rules in
flat config. Only the next lint wrapper command is removed. The package
is alive and is what you import from in eslint.config.mjs.

Fix: Parsing error: Cannot find module 'next/babel' — the other common Next.js lint error, separate from the flat-config migration.
Next.js build MODULE_NOT_FOUND fix — when a Next.js 16 upgrade pulls in a missing dependency.
Next.js 15 minimum Node.js version (18.18.0) — the Node version floor that also applies to Next.js 16 and to the ESLint 9 CLI.
Next.js + Supabase CI/CD with GitHub Actions — where the npm run lint CI step belongs in a full-stack pipeline.
Next.js + Supabase common mistakes — adjacent production pitfalls beyond linting.

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

How to Show Tables in PostgreSQL (psql + Supabase)

Mahdi BEN RHOUMA — Sat, 25 Jul 2026 15:03:43 +0000

The one-line answer

There is no SHOW TABLES in PostgreSQL. The psql client gives you \dt;
every other client gives you information_schema.tables. That is the whole
article in two commands:

-- psql
\dt

-- any client (Supabase SQL editor, Drizzle Studio, DataGrip, pgAdmin)
SELECT table_name
FROM information_schema.tables
WHERE table_schema = 'public'
ORDER BY table_name;

The rest of this article is the part that costs you an hour the first time:
schema filtering, sizes, system tables, Supabase specifics, and the three
reasons your query returns zero rows.

Method 1: `\dt` in psql

\dt is a psql meta-command, not SQL. It only works inside the psql
client. The official PostgreSQL psql documentation documents it
under the relation-listing group:

Command	What it lists
`\dt`	User tables in the current schema search path
`\dt+`	Same, plus on-disk size, persistence, description
`\dtS`	Include system tables (the `S` means "system")
`\dt schema.*`	Tables in a specific schema
`\dt public.users`	A specific table, if it exists

-- List your tables
\dt

-- List with size and description
\dt+

-- List only tables in the "auth" schema
\dt auth.*

-- Include system tables (rarely what you want)
\dtS

The single most common mistake: running \dt in the Supabase SQL
editor, Drizzle Studio, or pgAdmin and getting a syntax error. Backslash
commands are psql-only — they are interpreted by the psql client before
the query ever reaches the server. Any client that is not psql will send
\dt to PostgreSQL as SQL, where it is a syntax error.

Illustration — not a live capture. Example only; the column structure and table sample are quoted from the official PostgreSQL psql documentation and a typical Supabase-style schema. The orange banner inside the image is the renderer-level "not a live capture" badge.

`\d` vs `\dt`

\d without arguments lists every relation — tables, views, materialized
views, sequences, and foreign tables. It is the same as \dtvmsE. If you
only want tables, use \dt. If you want a single relation's schema (the
MySQL DESCRIBE table equivalent), use \d table_name — covered in the
PostgreSQL DESCRIBE TABLE equivalent.

Method 2: `information_schema.tables` (portable SQL)

This is the query that works everywhere — psql, Supabase SQL editor, Drizzle
Studio, DataGrip, pgAdmin, any driver. It is the SQL-standard way and the
only way in the Supabase SQL editor.

-- All tables in the public schema
SELECT table_name
FROM information_schema.tables
WHERE table_schema = 'public'
  AND table_type = 'BASE TABLE'
ORDER BY table_name;

The table_type = 'BASE TABLE' filter excludes views. Without it you get
both tables and views in the result.

Why you must filter by schema

information_schema.tables returns every table the server knows about,
including the system catalogs. Run this without a filter:

SELECT table_schema, table_name
FROM information_schema.tables
ORDER BY table_schema, table_name;

You will get hundreds of rows from pg_catalog (the system catalog) and
information_schema itself. Those are not your tables. Always filter on
table_schema unless you genuinely want the system schemas:

-- Only your app tables (typical)
WHERE table_schema = 'public'

-- Multiple app schemas
WHERE table_schema IN ('public', 'auth', 'storage')

-- Everything except system schemas
WHERE table_schema NOT IN ('pg_catalog', 'information_schema', 'pg_toast')

List all tables across all schemas (excluding system schemas)

SELECT table_schema, table_name
FROM information_schema.tables
WHERE table_type = 'BASE TABLE'
  AND table_schema NOT IN ('pg_catalog', 'information_schema', 'pg_toast')
ORDER BY table_schema, table_name;

This is the query to reach for when you do not know which schemas your app
uses — for example, a Supabase project with public, auth, storage,
and a custom billing schema.

Method 3: `pg_class` (the most granular)

information_schema is the SQL standard, but it does not expose physical
metadata like on-disk size or row estimates. For that, query pg_class
directly. This is the approach the PostgreSQL docs describe
through the system catalogs.

-- List all user tables with their schema
SELECT n.nspname AS schema_name,
       c.relname AS table_name
FROM pg_class c
JOIN pg_namespace n ON n.oid = c.relnamespace
WHERE c.relkind = 'r'
  AND n.nspname NOT IN ('pg_catalog', 'information_schema')
ORDER BY n.nspname, c.relname;

relkind = 'r' means "ordinary heap table". Other useful values: p for
partitioned tables, v for views, m for materialized views, S for
sequences. If you want partitioned tables too, use c.relkind IN ('r', 'p').

List tables with their on-disk size

information_schema.tables does not expose size. Use pg_class with
pg_total_relation_size():

SELECT n.nspname AS schema_name,
       c.relname AS table_name,
       pg_size_pretty(pg_total_relation_size(c.oid)) AS total_size
FROM pg_class c
JOIN pg_namespace n ON n.oid = c.relnamespace
WHERE c.relkind IN ('r', 'p')
  AND n.nspname NOT IN ('pg_catalog', 'information_schema')
ORDER BY pg_total_relation_size(c.oid) DESC;

pg_total_relation_size() includes indexes and TOAST data, not just the
heap. If you want only the table heap, use pg_table_size(); if you want
only the indexes, use pg_indexes_size().

Approximate row counts

information_schema.tables does not give row counts either, and COUNT(*)
on every table is too expensive on a large database. Use the planner's
reltuples estimate:

SELECT c.relname AS table_name,
       c.reltuples::bigint AS approximate_row_count
FROM pg_class c
JOIN pg_namespace n ON n.oid = c.relnamespace
WHERE c.relkind = 'r'
  AND n.nspname = 'public'
ORDER BY c.reltuples DESC;

reltuples is updated by ANALYZE and is an estimate — good enough for
"which table is the big one" diagnostics. For exact counts you must run
SELECT COUNT(*) per table, which is a sequential scan. The
how to get count in Supabase article
covers the Supabase client side of the same problem.

Method 4: Supabase specifics

Supabase runs PostgreSQL, so every method above works in the Supabase SQL
editor with one constraint: the SQL editor is not psql, so backslash
commands do not work. Use information_schema.tables or pg_class.

The Table Editor (zero-SQL path)

If you just want to see your tables in a browser, the Supabase Dashboard has
a Table Editor: Dashboard → Table Editor. It lists every table in every
schema your service role can see, with row counts and a quick-edit view. For
a developer pasting \dt into Google, the SQL editor query above is faster.

Illustration — not a live capture. Example only; the comparison is synthesized from the official psql documentation and the Supabase Table Editor documentation. The orange banner inside the image is the renderer-level "not a live capture" badge.

Listing tables with RLS enabled

A common Supabase question is not "which tables exist" but "which tables
have row-level security enabled". That is a pg_class join against
pg_namespace with a check on relrowsecurity:

SELECT n.nspname AS schema_name,
       c.relname AS table_name,
       c.relrowsecurity AS rls_enabled
FROM pg_class c
JOIN pg_namespace n ON n.oid = c.relnamespace
WHERE c.relkind = 'r'
  AND n.nspname = 'public'
ORDER BY c.relrowsecurity DESC, c.relname;

relrowsecurity is true when RLS is enabled. To go deeper — auditing the
actual policies, not just the flag — see the
Supabase RLS policy design patterns
guide and the debugging Supabase RLS issues
post.

Listing tables in a specific schema (auth, storage, realtime)

Supabase ships non-public schemas. To list tables in auth (Supabase
Auth's internal schema) or storage (Supabase Storage):

SELECT table_name
FROM information_schema.tables
WHERE table_schema = 'auth'
ORDER BY table_name;

Note: you will only see these schemas if your role has been granted access.
The anon and authenticated roles do not have SELECT on most of auth
and storage; run these queries as the postgres role or a service role.

Why your query returns zero rows

Three causes cover almost every "I ran the query and got nothing" report.

1. You are connected to the wrong database

information_schema.tables is per-database. If you have two Supabase
projects and your connection string points at project A, you will not see
project B's tables. Confirm with:

SELECT current_database();

2. The schema name is wrong or quoted differently

PostgreSQL folds unquoted identifiers to lowercase. A table created as
CREATE TABLE "Users" lives in public.Users (capital U), but
WHERE table_schema = 'public' AND table_name = 'users' returns nothing
because the actual name is Users. Query without the name filter first,
then look at the exact table_name value.

3. Your role does not have access

information_schema.tables only shows tables the current role has
privileges on. The anon role in Supabase sees very little; the postgres
role sees everything. If you run the query as anon and get an empty
result, connect as postgres or your service role and re-run. This is the
same privilege model that produces the
Postgres peer authentication failed
error when the OS user does not match the database role.

Performance: do not `SELECT COUNT(*)` to list tables

The most expensive mistake on a large database is looping over every table
and running SELECT COUNT(*) FROM table. Each count is a sequential scan;
on a 50M-row table that is seconds to minutes. For "show tables with row
counts", use the reltuples estimate from pg_class (Method 3 above). Run
ANALYZE first if the estimate is stale:

ANALYZE;

ANALYZE updates planner statistics, including reltuples, and is
read-only with respect to user data — it does not lock tables for long. For
the Supabase client equivalent (counting rows from the browser), see
how to get count in Supabase, which
covers the head: true trick that avoids fetching rows.

Production recommendations

Use information_schema.tables for any non-psql client. It is the only portable way. Backslash commands will fail in the Supabase SQL editor, Drizzle Studio, and most ORMs.
Always filter on table_schema. Without a filter you get hundreds of system tables that obscure your actual tables.
Use pg_class for size and row estimates. information_schema.tables does not expose physical metadata; pg_class does.
Run ANALYZE before trusting reltuples. The estimate is only as fresh as the last ANALYZE. On Supabase, the autovacuum default keeps it reasonably fresh, but a bulk import will leave it stale until the next run.
For schema auditing, combine pg_class with pg_namespace and pg_description. That gives you table, schema, size, RLS flag, and comment in one query — the basis of any database design optimization review.

Listing views, materialized views, and sequences too

\dt lists only heap tables. Real schemas also contain views, materialized
views, and sequences — and "show me everything in this schema" is a
different question from "show me the tables". Each has its own psql
meta-command and its own relkind filter in pg_class.

Object type	psql command	`relkind`	`information_schema` view
Tables	`\dt`	`r` (heap) or `p` (partitioned)	`information_schema.tables`
Views	`\dv`	`v`	`information_schema.views`
Materialized views	`\dm`	`m`	(none — query `pg_class`)
Sequences	`\ds`	`S`	`information_schema.sequences`
Everything	`\d`	`r,p,v,m,S,f`	(no single view)

To list every relation in the public schema regardless of type, in any
client:

SELECT c.relkind AS kind,
       n.nspname AS schema_name,
       c.relname AS relation_name
FROM pg_class c
JOIN pg_namespace n ON n.oid = c.relnamespace
WHERE n.nspname = 'public'
  AND c.relkind IN ('r', 'p', 'v', 'm', 'S')
ORDER BY c.relkind, c.relname;

This is the query to run when you inherit a database and need to know what
is in it before you touch anything. Materialized views are particularly
easy to miss because they do not show up in \dt and have no row in
information_schema.tables with table_type = 'BASE TABLE' — they are a
distinct relkind = 'm' and only appear in pg_class.

Refreshing materialized views

A materialized view is a stored query result. It does not update
automatically; you refresh it with REFRESH MATERIALIZED VIEW view_name;. If you are listing tables to find "why is this data stale", the
materialized view is the usual suspect. List them first with \dm in psql
or the relkind = 'm' query above, then check each one's last refresh time
through pg_stat_user_tables — there is no native "last refreshed" column,
so most teams track it themselves.

FAQ

Is `\dt` the same as `SHOW TABLES`?

No. SHOW TABLES is a MySQL statement; PostgreSQL does not have it. \dt
is a psql client command that lists tables. They serve the same purpose for
the user, but \dt never leaves the psql client — it is not SQL.

How do I list tables in a specific schema?

In psql: \dt schema_name.*. In any other client:
SELECT table_name FROM information_schema.tables WHERE table_schema = 'schema_name';.

How do I see table sizes in PostgreSQL?

\dt+ in psql, or query pg_class with pg_total_relation_size(c.oid).
information_schema.tables does not expose size.

How do I list only partitioned tables?

In pg_class, filter on relkind = 'p'. In information_schema.tables,
partitioned tables appear with table_type = 'BASE TABLE' — the view does
not distinguish partitioned from heap tables, which is a reason to use
pg_class for physical metadata.

PostgreSQL DESCRIBE TABLE: the psql \d equivalent — the sibling article for inspecting a single table's columns, types, and constraints.
How to get count in Supabase — the Supabase client side of "how many rows", including the head: true trick.
Supabase RLS policy design patterns — for auditing which tables have RLS and what the policies do.
Supabase Postgres functions and triggers guide — for listing and inspecting functions and triggers alongside your tables.
Next.js + Supabase database design optimization — where table listing fits into a schema review.
Postgres peer authentication failed fix — when "I cannot see my tables" is actually a role/auth problem.

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

How to Change a PostgreSQL User Password (Supabase)

Mahdi BEN RHOUMA — Sat, 25 Jul 2026 15:03:35 +0000

The one-line answer

ALTER ROLE alice WITH PASSWORD 'new_password';

That is the SQL. The rest of this article is about doing it safely — without
leaving the cleartext in your shell history, without breaking Supabase
managed connections, and without forgetting the connection string in your
production app.

Illustration — not a live capture. Example diagram only; the steps are synthesized from this article and the official PostgreSQL ALTER ROLE / pg_terminate_backend documentation. The orange banner inside the image is the renderer-level "not a live capture" badge.

The PostgreSQL ALTER ROLE documentation is the
authoritative source for the syntax; this article adds the operational
context the docs do not.

Method 1: `ALTER ROLE ... PASSWORD` (the SQL way)

The canonical command from the PostgreSQL docs:

-- Set a password
ALTER ROLE alice WITH PASSWORD 'hunter2';

-- Remove a password (set to NULL — role can still connect if other auth methods allow)
ALTER ROLE alice WITH PASSWORD NULL;

ALTER USER is a legacy alias for ALTER ROLE and behaves identically. The
docs are explicit: ALTER USER "is accepted for backward compatibility, but
the canonical command is ALTER ROLE." Use ALTER ROLE in new code.

The `ENCRYPTED` keyword is optional and the default

-- These two are equivalent
ALTER ROLE alice WITH ENCRYPTED PASSWORD 'hunter2';
ALTER ROLE alice WITH PASSWORD 'hunter2';

The ENCRYPTED keyword is optional. The server encrypts the password with
the algorithm set by password_encryption — scram-sha-256 by default
since PostgreSQL 13. You almost never need to write ENCRYPTED explicitly.

Why `ALTER ROLE` leaks the password into logs

The docs warn about this directly:

Caution must be exercised when specifying an unencrypted password with
this command. The password will be transmitted to the server in cleartext,
and it might also be logged in the client's command history or the server
log.

If you type ALTER ROLE alice WITH PASSWORD 'hunter2'; in psql, the string
hunter2 lands in ~/.psql_history. If statement logging is on, it lands
in the server log too. For a personal dev database that is fine. For
production it is not. Use Method 2.

Method 2: `\password` in psql (the safe way)

psql ships a meta-command that prompts for the new password interactively
and never writes the cleartext to history or logs:

\password alice

It asks for the new password twice (to confirm) and sends an ALTER ROLE
to the server with the password already encrypted by the client. This is
the method the PostgreSQL docs recommend for any password change you do
interactively. Use it whenever you are in psql.

Method 3: Reset the `postgres` role in Supabase

Supabase manages the postgres role for you. You can run
ALTER ROLE postgres WITH PASSWORD '...' in the SQL editor, but the
recommended path is the Dashboard, because Supabase-managed services
(PgBouncer, PostgREST, GoTrue, the Studio itself) need their connection
strings rotated too. The Dashboard reset does that for you.

Open your Supabase project Dashboard.
Go to Database → Settings (also reachable via Project Settings → Database).
Locate the Database password section ("Used for direct Postgres connections").
Click Reset password.

What happens automatically:

The postgres role password is rotated.
Supabase-managed services (PostgREST, PgBouncer, Realtime, GoTrue, Studio) pick up the new password with no downtime.
The connection string shown in the Dashboard updates.

What does not happen automatically, and this is where production
breaks:

Hardcoded connection strings in your Next.js app do not update. If your DATABASE_URL env var has the old password baked in, the app starts failing with password authentication failed for user "postgres" on the next connection.
CI secrets do not update. GitHub Actions secrets holding the old password keep sending it until you rotate them.
.pgpass files on your machine do not update. psql will fall back to prompting or fail non-interactively.
External services (cron jobs, n8n workflows, backup scripts) do not update. Every one of them breaks on the next connection attempt.

The password is not retrievable after reset — Supabase does not store it in
cleartext. Save it somewhere safe the first time.

`password_encryption`: scram-sha-256 vs md5

The PostgreSQL ALTER ROLE docs state that the password
is encrypted with the algorithm set by password_encryption. Since
PostgreSQL 13 the default is scram-sha-256:

SHOW password_encryption;
--  password_encryption
-- ---------------------
--  scram-sha-256

If the value is md5, your cluster is running a pre-13 config or someone
changed it. You can change it for the current session:

SET password_encryption = 'scram-sha-256';
ALTER ROLE alice WITH PASSWORD 'hunter2';
RESET password_encryption;

A password set while password_encryption = 'scram-sha-256' is stored as a
SCRAM verifier in pg_authid.rolpassword (starts with SCRAM-SHA-256$). A
password set while password_encryption = 'md5' is stored as an md5 hash
(starts with md5). A role with an md5 password cannot authenticate to a
server that requires scram-sha-256 in pg_hba.conf, and vice versa —
this is the most common cause of
password authentication failed
after a migration.

Why authentication breaks after a password change

After you run ALTER ROLE alice WITH PASSWORD 'newpass', every existing
connection stays open until it disconnects — the password is only
checked at connection time. The breakage starts on the next connection
attempt from anywhere that still has the old password:

Your Next.js app. The DATABASE_URL env var in Vercel/Cloudflare has the old password. The Next time the app opens a new connection (which happens on cold start or when the pool expands), it fails. Update the env var and redeploy. The Supabase connection pooling guide covers where this env var belongs in a Vercel deployment.
Your CI pipeline. GitHub Actions secrets still hold the old password. Migration jobs fail with password authentication failed for user "postgres". Rotate the secret.
.pgpass. ~/.pgpass has the old password on a line like db.x.supabase.co:5432:*:postgres:oldpass. Update it, or delete the line and let psql prompt.
External services. Any n8n workflow, cron job, or backup script with a hardcoded connection string must be updated.

The safe rotation sequence is:

Add a new role with the new password (or reset the existing one in Supabase).
Update every consumer (app, CI, .pgpass, external services) to the new password.
Redeploy / reconnect.
Only then, if you rotated by creating a new role, revoke the old role.

For the postgres role in Supabase you cannot create a parallel role —
Supabase owns postgres. The sequence is: reset in the Dashboard, update
every consumer, redeploy.

The `.pgpass` file

~/.pgpass is the psql way to avoid typing passwords. Each line is:

hostname:port:database:username:password

For Supabase:

db.abcdefghijklmnop.supabase.co:5432:*:postgres:your-new-password

After a password change, edit the line. If you used the Supabase Dashboard
reset and your password contains special characters (:, @, /, etc.),
you must percent-encode them in a connection string (postgres://...) but
not in .pgpass — .pgpass stores the literal password.

Production recommendations

Prefer \password over ALTER ROLE ... PASSWORD in psql. The cleartext never hits history or logs. This is the single most important habit.
Use scram-sha-256. It is the default since PostgreSQL 13; do not downgrade to md5. If SHOW password_encryption; returns md5, investigate why — it usually means the cluster was initialized on an old config.
Rotate the postgres role from the Supabase Dashboard, not from SQL. The Dashboard reset rotates managed services for you; an ALTER ROLE postgres in the SQL editor does not, and you will spend the next hour debugging why PostgREST 401s.
Update every consumer before you rotate, or accept a brief outage. The only safe zero-downtime rotation for a single-role setup is to create a new role, switch consumers to it, then revoke the old one.
Percent-encode special characters in connection strings. A password like p@ss:w/ord must become p%40ss%3Aw%2Ford in a postgres:// URL. In .pgpass it stays literal.
Audit pg_authid.rolpassword after rotation. Every active role's password should start with SCRAM-SHA-256$. Anything starting with md5 is a role that has not had its password reset since before the scram-sha-256 default — a finding worth noting in a security best-practices review.
Do not store the password in the repo. Use env vars and a secret manager. If a password ends up in git, rotate it immediately — git filter-repo is not a substitute for rotation, because the hash is already public.

Common pitfalls

`ALTER USER` vs `ALTER ROLE` confusion

They are the same. If you find old scripts using ALTER USER, they work;
ALTER USER is a legacy alias. Update them to ALTER ROLE for clarity but
do not treat it as a bug.

Password change does not kick existing sessions

Existing connections stay open. If you are rotating because a password
leaked, you must also terminate existing sessions:

SELECT pg_terminate_backend(pid)
FROM pg_stat_activity
WHERE usename = 'alice'
  AND pid <> pg_backend_pid();

Otherwise a session opened before the rotation keeps running with the old
auth context until it disconnects. For a production rotation triggered by a
credential leak, run the pg_terminate_backend query immediately after the
ALTER ROLE so no attacker holds an open session with the old password.

md5-to-scram migration leaves roles unable to connect

If you change password_encryption to scram-sha-256 and a role has an
md5 password, that role cannot authenticate through a scram-sha-256
pg_hba.conf entry. Re-set the password with ALTER ROLE ... PASSWORD
after switching password_encryption, so the new verifier is stored as
SCRAM. The same trap in reverse is why
peer authentication failed
appears after a version upgrade.

Supabase connection pool keeps old password

Supabase's PgBouncer pool is managed and rotates automatically on a
Dashboard reset — you do not need to restart the pooler yourself. But
if you use a direct (non-pooled) connection string in your app, you bypass
PgBouncer — the app authenticates to Postgres directly, and a stale
connection string fails. Use the pooled connection string
(*.pooler.supabase.com:6543) for the app and the direct string only for
migrations. The
connection pooling guide
has the exact env vars.

Concurrent `ALTER ROLE` during a migration

Two migrations changing the same role's password at the same time race.
The second one wins; the first password is lost. If you run migrations in
parallel, serialize password changes. For the broader concurrency story —
serializable transactions and could not serialize access — see
could not serialize access: concurrent update in Supabase.

FAQ

How do I change the `postgres` password without downtime?

In a single-role Supabase setup you cannot — the reset is atomic and
managed connections rotate, but hardcoded connection strings break on the
next reconnect. The zero-downtime pattern is: create a new role with the
new password, switch every consumer to it, then revoke the old role. For
the Supabase-managed postgres role, use the Dashboard reset and update
every consumer immediately after.

What does `\password` do that `ALTER ROLE` does not?

It prompts interactively, sends the password to the server already
encrypted by the client, and does not write the cleartext to
.psql_history or the server log. Use it for any interactive password
change.

Can I see the current password?

No. PostgreSQL stores a one-way hash (SCRAM-SHA-256 verifier or md5) in
pg_authid.rolpassword. You can read the hash but you cannot reverse it
to the cleartext. If you lost the password, reset it — there is no recovery.

Should I use `ALTER USER` or `ALTER ROLE`?

ALTER ROLE. ALTER USER is a legacy alias that works identically, but
ALTER ROLE is the canonical command in the PostgreSQL documentation.

Postgres peer authentication failed fix — the error you get after a password change with a stale pg_hba.conf or md5/scram mismatch.
PostgreSQL DESCRIBE TABLE: the psql \d equivalent — the sibling psql-meta-command reference for inspecting a table's schema.
Supabase connection pooling on Vercel — where the password lives in a Vercel deployment and the pooled vs direct connection strings.
Next.js + Supabase security best practices — where password rotation fits into a broader production security review.
Could not serialize access: concurrent update in Supabase — the concurrency side of running migrations and role changes in parallel.
How to create an enum column in Supabase — another common Supabase SQL-editor operation that differs from raw Postgres.

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

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

DEV Community: Mahdi BEN RHOUMA

Next.js 16 Removed next lint: ESLint 9 Migration

What actually broke in Next.js 16

The 30-second path: run the official codemod

Writing eslint.config.mjs by hand

Why not defineConfig and globalIgnores

package.json scripts that replace next lint

Migrating from a legacy .eslintrc.json

The .eslintrc plugins that have not migrated

CI/CD: where the silent break lives

The ignoreDuringBuilds trap

Common pitfalls, ranked by how often they bite

A note on Turbopack

Verifying the migration worked

Production recommendations

FAQ

Should I migrate to ESLint 9 or wait for ESLint 10?

Can I use Biome instead of ESLint in Next.js 16?

What about the eslint-config-next package — is it deprecated?

Related

How to Show Tables in PostgreSQL (psql + Supabase)

The one-line answer

Method 1: \dt in psql

\d vs \dt

Method 2: information_schema.tables (portable SQL)

Why you must filter by schema

List all tables across all schemas (excluding system schemas)

Method 3: pg_class (the most granular)

List tables with their on-disk size

Approximate row counts

Method 4: Supabase specifics

The Table Editor (zero-SQL path)

Listing tables with RLS enabled

Listing tables in a specific schema (auth, storage, realtime)

Why your query returns zero rows

1. You are connected to the wrong database

2. The schema name is wrong or quoted differently

3. Your role does not have access

Performance: do not SELECT COUNT(*) to list tables

Production recommendations

Listing views, materialized views, and sequences too

Refreshing materialized views

FAQ

Is \dt the same as SHOW TABLES?

How do I list tables in a specific schema?

How do I see table sizes in PostgreSQL?

How do I list only partitioned tables?

Related

How to Change a PostgreSQL User Password (Supabase)

The one-line answer

Method 1: ALTER ROLE ... PASSWORD (the SQL way)

The ENCRYPTED keyword is optional and the default

Why ALTER ROLE leaks the password into logs

Method 2: \password in psql (the safe way)

Method 3: Reset the postgres role in Supabase

password_encryption: scram-sha-256 vs md5

Why authentication breaks after a password change

The .pgpass file

Production recommendations

Common pitfalls

ALTER USER vs ALTER ROLE confusion

Password change does not kick existing sessions

md5-to-scram migration leaves roles unable to connect

Supabase connection pool keeps old password

Concurrent ALTER ROLE during a migration

FAQ

How do I change the postgres password without downtime?

What does \password do that ALTER ROLE does not?

Can I see the current password?

Should I use ALTER USER or ALTER ROLE?

Related

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

Writing `eslint.config.mjs` by hand

Why not `defineConfig` and `globalIgnores`

`package.json` scripts that replace `next lint`

Migrating from a legacy `.eslintrc.json`

The `.eslintrc` plugins that have not migrated

The `ignoreDuringBuilds` trap

What about the `eslint-config-next` package — is it deprecated?

Method 1: `\dt` in psql

`\d` vs `\dt`

Method 2: `information_schema.tables` (portable SQL)

Method 3: `pg_class` (the most granular)

Performance: do not `SELECT COUNT(*)` to list tables

Is `\dt` the same as `SHOW TABLES`?

Method 1: `ALTER ROLE ... PASSWORD` (the SQL way)

The `ENCRYPTED` keyword is optional and the default

Why `ALTER ROLE` leaks the password into logs

Method 2: `\password` in psql (the safe way)

Method 3: Reset the `postgres` role in Supabase

`password_encryption`: scram-sha-256 vs md5

The `.pgpass` file

`ALTER USER` vs `ALTER ROLE` confusion

Concurrent `ALTER ROLE` during a migration

How do I change the `postgres` password without downtime?

What does `\password` do that `ALTER ROLE` does not?

Should I use `ALTER USER` or `ALTER ROLE`?

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

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