Keep supabase-js and the Supabase CLI up to date without breaking your app

Updated 2026-11-03

The JavaScript client and the Supabase CLI are different releases. The client’s current latest line is still v2. The CLI’s latest line is v3, and v3 runs database commands against the local stack unless you pass --remote. Update the client on v2, and read the v3 migration before you let the CLI move.

A Lovable or Bolt app that talks to your Supabase project usually depends on @supabase/supabase-js. Scripts and CI may also install the supabase CLI. Bumping “Supabase” as one version number updates the wrong thing, or both things, in one commit. The client install is documented at JavaScript: Installing. The CLI install and update commands are in the CLI getting-started guide. Schema changes still go through migration files, as in running Supabase migrations safely.

See which client and which CLI you have

npm ls @supabase/supabase-js @supabase/ssr @supabase/auth-helpers-nextjs supabase
npx supabase --version
supabase --version

The last command matters only when a binary is on your PATH, usually from Homebrew or Scoop. It can be a different major from the supabase devDependency npx runs. Trust the one your scripts invoke. npm ls prints empty or an error for a package the project does not depend on. That is fine. Note which of the four names are actually installed. Also search the repo for @supabase/auth-helpers-. Next.js, SvelteKit, and Remix each had a helper package.

The CLI needs Node.js 20 or newer when you run it through npm or npx. The JavaScript client has a separate requirement: current @supabase/supabase-js v2 releases require Node.js 22 or newer when running in Node, following Supabase’s end of Node.js 20 support. Check node -v, the package’s engines field, and your CI and SSR/server hosting runtimes before updating the client. Meeting the CLI requirement alone is not enough.

Update supabase-js on the current major

On 3 November 2026 the latest dist-tag of @supabase/supabase-js is still a v2 release. A next tag points at a v3 prerelease. A routine update should stay on v2 until that prerelease has a migration guide you have read. Pin the major:

npm install @supabase/supabase-js@2
npm ls @supabase/supabase-js

Commit package.json and the lockfile. Do not pass @next or @beta. If the app already uses @supabase/ssr, update that package in its own commit and run the sign-in path. @supabase/ssr is what reads and writes session cookies for a server-rendered app. The client library alone does not refresh those cookies.

If you are still on supabase-js v1, the jump to v2 is the v1 upgrade guide, not this patch step. Auth calls become explicit (signInWithPassword, signInWithOtp, getSession), and insert, update, upsert, and delete do not return rows unless you chain .select(). Do that migration on a branch, with the app running.

Replace deprecated auth helpers before a routine bump

Supabase’s migration from Auth Helpers replaces @supabase/auth-helpers-nextjs, and the SvelteKit and Remix helpers, with @supabase/ssr. Uninstall the helper you import. Install the SSR package. Do not leave both installed. Supabase’s troubleshooting note says the two clients in one app cause authentication bugs.

npm uninstall @supabase/auth-helpers-nextjs
npm install @supabase/ssr

createBrowserClient replaces the browser helper. createServerClient replaces the server and middleware helpers. The cookie adapter has to be wired again. Follow the migration page for the framework you use rather than renaming imports and keeping the old function calls. On the server, do not trust getSession() alone. Supabase’s server-client guide says the session is read from cookies without a new check, so anyone who can forge the cookie can be treated as that user. Use getClaims() when you are deciding whether a request is allowed. Use getUser() when you need a fresh user record from Auth. Use getSession() when you need the access token itself, and still verify before you authorize.

Update the CLI only after you read its major notes

Installing the CLI as a devDependency keeps laptops and CI on one version. The getting-started guide’s update, inside the range you already pinned, is:

npm update supabase --save-dev
npx supabase --version

npm install supabase@latest --save-dev is a different command. The latest tag is CLI v3. Homebrew’s brew upgrade supabase updates that v3 formula. The v2 formula is supabase@2, and the two conflict. v3 is a major change, documented in Migrating to Supabase CLI v3. Stay on the maintained v2 line until you have done the reading:

npm install supabase@v2.stable --save-dev

v2 still receives security fixes and fixes for broken behavior, and not new features. v2.122 and later warn about commands v3 removes. Update to v2.stable, run the commands you actually use, and fix those warnings before you consider v3.

Two v3 changes break hosted projects when someone treats the upgrade as a no-op. Database commands, including db push, db pull, db dump, and gen types, target the local stack unless you pass --remote. A bare supabase db push on v3 does not update the linked host. During the transition, supabase db push --linked --yes still targets the linked project on both majors, and v3 prints a warning that names --remote. Hosted changes also ask for confirmation, and the default answer is No. In CI, or when an agent runs the command, the CLI does not prompt. Pass --yes only on the command you meant. Piping echo y no longer confirms anything. SUPABASE_YES inside a project .env does not count either.

Before removing local data volumes, save local schema changes as migration files and export any data you need to keep. Follow Supabase’s backup and upgrade procedure for your installed CLI major, and verify those files before the destructive shutdown. Deleting volumes erases the local database; stopping containers alone is different. Restore the saved migrations and data after upgrading the local stack. Never reset the hosted database as part of a CLI upgrade.

Prove the app and the hosted project still match

Updating the CLI does not apply migrations and does not deploy functions. Run those only when you intend to, with the target flag the major you installed expects. Generating types with no target, on v3, reads the local database. For the hosted project use supabase gen types typescript --remote, and do not commit types from a different project than the one the app uses.

npm test
npm run build

Then sign in, sign out, and load one page that reads a table through the browser client. A failure there is the client or the SSR helper, not a reason to run db push. If you do push migrations, use the dry run from the migrations guide against the project you linked, and read which database it names before you confirm.

Keep the client commit and the CLI commit apart. A broken sign-in is much easier to undo when the diff does not also change every CLI flag in CI.

For weekly upkeep, you can manually create a recurring dependency-review task with Denly’s task schedules after connecting a project and runner. Configure its instructions and review gates before enabling it. The public report form below creates a report; it does not create a schedule or a pull request.

Commands and product behavior on this page were checked against the vendor documentation linked here on 3 November 2026. Those products change their screens. If a label has moved, follow the linked page rather than a memory of this one.

Read next

Run Supabase migrations safely in a Lovable project · How to update a Lovable project: GitHub sync and a one-time export