@bitwo.io/nuxt-supabase

Nuxt 3 module that exposes lightweight Supabase composables for both the browser and the server, ensuring the right credentials are used in each environment.

• ✨  Release Notes

Features

• 🔒 Separate browser (useSupabase) and server (useSupabaseServer) clients with strict guardrails.
• ⚙️ Runtime config + env variable wiring for NUXT_PUBLIC_SUPABASE_URL, NUXT_PUBLIC_SUPABASE_KEY, and NUXT_SUPABASE_SECRET_KEY (fallback support for SUPABASE_*).
• 🧩 Automatic composable auto-imports for a frictionless developer experience.

Quick Setup

Install the module in your Nuxt application:

# npm
npx nuxi@latest module add @bitwo.io/nuxt-supabase

# or Bun
bunx nuxi@latest module add @bitwo.io/nuxt-supabase

Then enable it inside nuxt.config.ts:

export default defineNuxtConfig({
  modules: ['@bitwo.io/nuxt-supabase'],
  supabase: {
    // Optional overrides if you do not rely on env variables
    supabaseUrl: process.env.NUXT_PUBLIC_SUPABASE_URL,
    supabasePublishableKey: process.env.NUXT_PUBLIC_SUPABASE_KEY,
    supabaseSecretKey: process.env.NUXT_SUPABASE_SECRET_KEY,
  },
})

Set the required environment variables (preferred) so they propagate to runtime config automatically:

NUXT_PUBLIC_SUPABASE_URL="https://your-instance.supabase.co"
NUXT_PUBLIC_SUPABASE_KEY="public-anon-key"
NUXT_SUPABASE_SECRET_KEY="service-role-key"

The module also reads legacy SUPABASE_URL, SUPABASE_KEY, and SUPABASE_SECRET_KEY names as a fallback.

Usage

// Client-side usage
const supabase = useSupabase()
const { data } = await supabase.from('todos').select('*')

// Server-side usage
const supabaseServer = useSupabaseServer()
await supabaseServer.from('todos').insert({ title: 'Secure insert' })

Both composables are singletons on their respective runtimes and throw descriptive errors if configuration is missing or the wrong environment is used.

Contribution

# Install dependencies
npm install

# Generate type stubs
npm run dev:prepare

# Develop with the playground
npm run dev

# Build the playground
npm run dev:build

# Run ESLint
npm run lint

# Run Vitest
npm run test
npm run test:watch

# Release new version
npm run release