@nuxtjs/supabase: wiring the Supabase client into a Nuxt application

A module that removes the client wiring, not the client

The nuxt-modules/supabase project is a Nuxt module for Supabase, published to npm as @nuxtjs/supabase, with its documentation hosted at supabase.nuxtjs.org.

The problem it addresses is narrow and real. Supabase ships supabase-js, a JavaScript client, and it behaves differently depending on where it runs. In the browser it can hold a session and refresh tokens. On the server it must not, because a long lived server process sharing one client between users leaks one visitor's session into another visitor's request. The module's answer is to depend on the SSR-aware client, `@supabase/ssr`, so that the cookie based session handling is correct on both sides.

Who it is for is a Nuxt application that already has a Supabase project and wants authentication and data access without hand rolling the client creation, the cookie handling and the type wiring. The feature list is short and specific: Nuxt 3 and 4 readiness, Vue 3 composables, usage in API server routes, authentication support, the isomorphic supabase-js client, and TypeScript support.

What it is not is a Supabase replacement. The database, the auth server, the row level security policies and the storage buckets all live in Supabase. This package is the binding layer between that backend and the Nuxt rendering model, and it will only be as good as the policies you wrote on the other side of the connection.

Three runtime dependencies and what each one carries

The dependency list in package.json is short enough to read as a design statement.

  "dependencies": {
    "@supabase/ssr": "^0.12.7",
    "@supabase/supabase-js": "^2.117.3",
    "defu": "^6.1.7",
    "pathe": "^2.0.3"
  },

The two Supabase packages are the substance. `@supabase/ssr` is the server side rendering aware layer, and `@supabase/supabase-js` is the client itself, pinned to a 2.x range. Both are caret ranges, which means a fresh install can pick up a newer minor version of either without the module changing.

`defu` is a deep merge utility, and in a Nuxt module it is how module options are combined with user options so that a user setting does not wipe out a default the module needs. `pathe` is a path helper that normalises file paths across operating systems, which matters for a module that has to resolve generated files in a project directory.

The module itself is built with `@nuxt/module-builder` and published as a single entry point, the module file, with the `dist` directory as the only shipped content.

  "exports": {
    ".": {
      "import": "./dist/module.mjs"
    }
  },
  "main": "./dist/module.mjs",
  "files": [
    "dist"
  ],

That is a small published surface, which is what you want from a module whose job is to run setup code inside a Nuxt build rather than to export a library you import by hand.

Composables in the browser, a usable client in server routes

Two of the listed features describe two different call sites, and the difference between them is where most of the integration risk sits.

The first is Vue 3 composables. A composable gives your components a reactive handle on the client, which is what you want for anything involving the signed in user: the session, the auth state, the ability to sign out. The naming and the exact shape of those composables are documented on the module's documentation site rather than in the repository README, which simply points readers there.

The second is usage in API server routes. This is the part that decides whether your project works in production. A Nuxt server route is a Node.js handler, so a browser client is the wrong thing to hand it. The isomorphic client the module depends on is the same object in both environments, which is why one dependency list can serve both the composables and the server routes.

The third feature, authentication support, sits on top of those two. Supabase's own auth flows involve redirects back into your application, and the redirect handling has to be consistent between the client that starts the flow and the server that completes it. A module that centralises client creation is also centralising that decision, which is a genuine benefit, although the specifics of the redirect configuration live in the documentation and not in the repository.

TypeScript support is listed as a feature, and the repository carries a typecheck script and a tsconfig, so the module is written in TypeScript. The published artefact is a single module file, so type declarations reach your project through the module's own generated types rather than through a hand written wrapper.

Working on the module, and what a consumer is pointed to instead

The README's usage section is a single sentence: check out the documentation site. There is no install snippet in the repository, and there are no consumer facing configuration examples, so this article will not invent any. The configuration keys, the environment variable names and the module options are all documented on supabase.nuxtjs.org, and that page is the reference you need before adding the module to a project.

What the repository does document is how to work on the module itself, and the steps are a pnpm based workflow.

pnpm install
pnpm dev:prepare
pnpm build
pnpm dev

Install the dependencies, prepare the development server, build the module, then launch the playground. The package metadata pins the package manager to a specific pnpm version, so using a different one will produce a different lockfile than the one in the repository.

The scripts in package.json show the wider workflow. `dev:prepare` runs the module builder in stub mode and then prepares the playground, the demo and the docs. The `verify` script chains the whole check.

"verify": "pnpm run dev:prepare && pnpm run lint && pnpm run typecheck && pnpm run test && pnpm run dev:build && pnpm build",

Lint, typecheck, tests, a playground build and a module build in one command. That is a sensible definition of done for a package whose only output is a single built file, and it is the command to run before opening a pull request against this repository.

The repository ships a demo, a playground and a docs site

The top level of the repository contains a `demo/` directory, a `playground/` directory and a `docs/` directory, alongside the `src/` and `test/` directories you would expect from a module. The demo has its own `nuxt.config.ts`, `app.vue`, `pages/`, `components/`, `layouts/`, `server/` and `types/` directories, which is the shape of a real application rather than a minimal example.

That demo directory is worth a look before you adopt the module, because it is the closest thing to a working configuration the repository offers. A `server/` directory in the demo tells you that the server route pattern is exercised somewhere in the project's own example application, and the `types/` directory suggests the demo is typed.

There is also a `vitest.config.ts` and a `test/` directory, and the `test` script runs `vitest run`. The presence of a test suite in the repository is a fact about the project rather than a claim about its quality, and the interesting part is what it can cover: a module's own option handling and the generation of its runtime code, rather than the behaviour of Supabase itself.

A few other files describe how the project is operated. There is a `renovate.json` for dependency updates, a `CHANGELOG.md` and a `CODE_OF_CONDUCT.md`, and a `pnpm-workspace.yaml` reflecting that the demo, playground and docs are separate workspaces. The `docs/` directory is what generates the site that the README keeps pointing you to.

Version numbers, release rhythm and who this module is not for

The release history shows v2.0.9 on 2026-05-21, v2.0.10 on 2026-08-10 and v2.1.0 on 2026-10-15. The jump from the 2.0.x line to 2.1.0 is the kind of minor bump that in a Nuxt module often means new options or a change in defaults, so reading the changelog at supabase.nuxtjs.org before upgrading from a 2.0.x pin is worth the minute it takes.

The repository is not archived and the last push was on 2026-10-19, four days after the most recent release, so the two facts are consistent with a project that is being worked on.

The licence field on the repository says MIT, and the README links to the MIT License file. For a module that talks to a hosted backend you did not write, that is the least of the licensing questions you will have; the Supabase service's own terms are a separate matter and nothing here is legal advice.

There is one clear exclusion, and it is stated in the README. If you are looking for a solution with Nuxt 2, the project points you to a different one, the supabase-community/nuxt-supabase repository. This module targets Nuxt 3 and Nuxt 4, and the package metadata reflects that with `@nuxt/kit` and `nuxt` in the 4.6 range.

The other alternative is the one this module exists to avoid: creating the Supabase client yourself with `@supabase/ssr` in a plugin. The difference in approach is that a plugin leaves the composables, the option merging and the server route story to you, and you would be re-solving the session and redirect problems for every project. The module's value is not that it calls Supabase, it is that it removes the repeated decisions around calling Supabase from a Nuxt app.

Editorial conclusion

Adopt @nuxtjs/supabase if your Nuxt app talks to Supabase on both the client and the server, since the module exists to keep those two sides on one client and one set of types. Do not adopt it for a Nuxt 2 codebase, where the documentation points to a different community module, and do not adopt it for a purely server-side script with no Nuxt at all. Before installing, read the configuration reference at supabase.nuxtjs.org for the environment variable names and redirect handling, and check that the pinned @supabase/supabase-js range in your lockfile matches the version your Auth setup expects.

Frequently asked questions

Official sources

1. License: MIT
2. nuxt-modules/supabase on GitHub
3. Project website
4. README
5. Releases