fix(env): support runtime nuxt env variables (#589)

Co-authored-by: Baptiste Leproux <leproux.baptiste@gmail.com>

Author: joris-sevenlab

demo/README.md

@@ -43,8 +43,8 @@ CREATE TABLE tasks (
 Go to your supabase project settings, API section and get the project API key and url and fill the `.env` with them:
 
 ```
-SUPABASE_URL="https://example.supabase.co"
-SUPABASE_KEY="<your_key>"
+NUXT_PUBLIC_SUPABASE_URL="https://example.supabase.co"
+NUXT_PUBLIC_SUPABASE_KEY="<your_key>"
 ```
 
 ### GitHub Oauth Setup

docs/content/1.getting-started/1.introduction.md

@@ -27,15 +27,15 @@ export default defineNuxtConfig({
 })
 ```
 
-Add `SUPABASE_URL` and `SUPABASE_KEY` to the `.env`:
+Add `NUXT_PUBLIC_SUPABASE_URL` and `NUXT_PUBLIC_SUPABASE_KEY` to the `.env`:
 
 ```bash [env]
-SUPABASE_URL="https://example.supabase.co"
-SUPABASE_KEY="<your_publishable_key>"
+NUXT_PUBLIC_SUPABASE_URL="https://example.supabase.co"
+NUXT_PUBLIC_SUPABASE_KEY="<your_publishable_key>"
 ```
 
 ::tip
-Alternatively, you can prefix the env variables with `NUXT_PUBLIC_` in order to use runtimeConfig.
+The legacy `SUPABASE_URL` and `SUPABASE_KEY` env variables are still supported as fallbacks. Using the `NUXT_` prefix is recommended as it follows Nuxt's [runtimeConfig](https://nuxt.com/docs/guide/going-further/runtime-config) convention and allows overriding values at runtime without rebuilding.
 ::
 
 ## Options
@@ -53,13 +53,13 @@ export default defineNuxtConfig({
 
 ### `url`
 
-Default: `process.env.SUPABASE_URL` (ex: <https://example.supabase.co>)
+Default: `NUXT_PUBLIC_SUPABASE_URL` env variable (falls back to `SUPABASE_URL`) (ex: <https://example.supabase.co>)
 
 The unique Supabase URL which is supplied when you create a new project in your project dashboard.
 
 ### `key`
 
-Default: `process.env.SUPABASE_KEY`
+Default: `NUXT_PUBLIC_SUPABASE_KEY` env variable (falls back to `SUPABASE_KEY`)
 
 Supabase `publishable key`, used to verify and decode the JWT. Can bypass the Supabase API gateway and interact with your Supabase database applying RLS Policies.
 
@@ -69,17 +69,17 @@ In `v1.x.x` and earlier, this was referring to the `anon key`. With the introduc
 
 ### `secretKey`
 
-Default: `process.env.SUPABASE_SECRET_KEY`
+Default: `NUXT_SUPABASE_SECRET_KEY` env variable (falls back to `SUPABASE_SECRET_KEY`)
 
 Supabase `secret key`, has super admin rights and can bypass your Row Level Security.
 
 ::warning
-This key should be kept secret and never exposed to the client. Keep it in environment variables.
+This key is server-only and never exposed to the client. Keep it in environment variables.
 ::
 
 ### `serviceKey` :u-badge{label="Deprecated" color="warning"}
 
-Default: `process.env.SUPABASE_SERVICE_KEY`
+Default: `NUXT_SUPABASE_SERVICE_KEY` env variable (falls back to `SUPABASE_SERVICE_KEY`)
 
 ::warning{to="https://supabase.com/blog/jwt-signing-keys"}
 *Legacy API key* used before signing JWT keys were introduced. Use `secretKey` instead. This option will be removed in a future version.

docs/content/1.getting-started/4.migration.md

@@ -133,6 +133,10 @@ Before migrating your environment variables, you need to enable JWT signing keys
 #### 2.b. Use your new keys in your `.env` file
 
 ```bash [.env]
-SUPABASE_KEY=<your_publishable_key>
-SUPABASE_SECRET_KEY=<your_secret_key>
+NUXT_PUBLIC_SUPABASE_KEY=<your_publishable_key>
+NUXT_SUPABASE_SECRET_KEY=<your_secret_key>
 ```
+
+::tip
+The legacy `SUPABASE_KEY` and `SUPABASE_SECRET_KEY` env variables are still supported as fallbacks. See the [introduction](/getting-started/introduction) for details.
+::

docs/content/2.composables/useSupabaseClient.md

@@ -7,7 +7,7 @@ description: Make requests to the Supabase API with the useSupabaseClient compos
 
 This composable is using [supabase-js](https://github.com/supabase/supabase-js/) under the hood, it gives access to the [Supabase client](https://supabase.com/docs/reference/javascript/initializing).
 
-> The client is initialized with the `SUPABASE_KEY` you must have in your `.env` file. It establishes the connection with the database and make use of user JWT to apply [RLS Policies](https://supabase.com/docs/learn/auth-deep-dive/auth-row-level-security) implemented in Supabase. If you want to bypass policies, you can use the [serverSupabaseServiceRole](/services/serversupabaseservicerole).
+> The client is initialized with the `NUXT_PUBLIC_SUPABASE_KEY` you must have in your `.env` file. It establishes the connection with the database and make use of user JWT to apply [RLS Policies](https://supabase.com/docs/learn/auth-deep-dive/auth-row-level-security) implemented in Supabase. If you want to bypass policies, you can use the [serverSupabaseServiceRole](/services/serversupabaseservicerole).
 
 ## Authentication
 

docs/content/3.services/2.serverSupabaseServiceRole.md

@@ -14,7 +14,7 @@ This function is designed to work only in [server routes](https://nuxt.com/docs/
 
 It works similary as the [serverSupabaseClient](/services/serversupabaseclient) but it provides a client with super admin rights that can bypass your [Row Level Security](https://supabase.com/docs/guides/auth/row-level-security).
 
-> The client is initialized with the `SUPABASE_SECRET_KEY` (recommended) or `SUPABASE_SERVICE_KEY` (deprecated) you must have in your `.env` file. We recommend using the new JWT signing keys (`SUPABASE_SECRET_KEY`) as described in the [Supabase blog post](https://supabase.com/blog/jwt-signing-keys).
+> The client is initialized with the `NUXT_SUPABASE_SECRET_KEY` you must have in your `.env` file. See the [Supabase blog post](https://supabase.com/blog/jwt-signing-keys) for more on JWT signing keys.
 
 Define your server route and just import the `serverSupabaseServiceRole` from `#supabase/server`.
 

src/module.ts

@@ -13,7 +13,7 @@ export * from './types'
 export interface ModuleOptions {
   /**
    * Supabase API URL
-   * @default process.env.SUPABASE_URL
+   * @default process.env.NUXT_PUBLIC_SUPABASE_URL || process.env.SUPABASE_URL
    * @example 'https://*.supabase.co'
    * @type string
    * @docs https://supabase.com/docs/reference/javascript/initializing#parameters
@@ -22,7 +22,7 @@ export interface ModuleOptions {
 
   /**
    * Supabase Client publishable API Key (previously known as 'anon key')
-   * @default process.env.SUPABASE_KEY
+   * @default process.env.NUXT_PUBLIC_SUPABASE_KEY || process.env.SUPABASE_KEY
    * @example '123456789'
    * @type string
    * @docs https://supabase.com/docs/reference/javascript/initializing#parameters
@@ -31,7 +31,7 @@ export interface ModuleOptions {
 
   /**
    * Supabase Legacy 'service_role' key (deprecated)
-   * @default process.env.SUPABASE_SERVICE_KEY
+   * @default process.env.NUXT_SUPABASE_SERVICE_KEY || process.env.SUPABASE_SERVICE_KEY
    * @example '123456789'
    * @type string
    * @docs https://supabase.com/docs/reference/javascript/initializing#parameters
@@ -41,7 +41,7 @@ export interface ModuleOptions {
 
   /**
    * Supabase Secret key
-   * @default process.env.SUPABASE_SECRET_KEY
+   * @default process.env.NUXT_SUPABASE_SECRET_KEY || process.env.SUPABASE_SECRET_KEY
    * @example '123456789'
    * @type string
    * @docs https://supabase.com/blog/jwt-signing-keys
@@ -129,16 +129,20 @@ export default defineNuxtModule<ModuleOptions>({
     },
   },
   defaults: {
-    url: (process.env.SUPABASE_URL
-      ?? process.env.NUXT_PUBLIC_SUPABASE_URL) as string,
-    key: (process.env.SUPABASE_KEY
-      ?? process.env.SUPABASE_PUBLISHABLE_KEY
-      ?? process.env.NUXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY
-      ?? process.env.SUPABASE_ANON_KEY
-      ?? process.env.NUXT_PUBLIC_SUPABASE_ANON_KEY) as string,
-    serviceKey: process.env.SUPABASE_SERVICE_KEY as string,
-    secretKey: (process.env.SUPABASE_SECRET_KEY
-      ?? process.env.SUPABASE_SERVICE_ROLE_KEY) as string,
+    // Env var resolution order: NUXT_PUBLIC_*/NUXT_* (recommended) → SUPABASE_* (legacy fallback) → undefined
+    url: process.env.NUXT_PUBLIC_SUPABASE_URL
+      || process.env.SUPABASE_URL || undefined,
+    key: process.env.NUXT_PUBLIC_SUPABASE_KEY
+      || process.env.SUPABASE_KEY
+      || process.env.SUPABASE_PUBLISHABLE_KEY
+      || process.env.SUPABASE_ANON_KEY
+      || process.env.NUXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY
+      || process.env.NUXT_PUBLIC_SUPABASE_ANON_KEY || undefined,
+    serviceKey: process.env.NUXT_SUPABASE_SERVICE_KEY
+      || process.env.SUPABASE_SERVICE_KEY || undefined,
+    secretKey: process.env.NUXT_SUPABASE_SECRET_KEY
+      || process.env.SUPABASE_SECRET_KEY
+      || process.env.SUPABASE_SERVICE_ROLE_KEY || undefined,
     redirect: true,
     redirectOptions: {
       login: '/login',
@@ -185,7 +189,7 @@ export default defineNuxtModule<ModuleOptions>({
 
     // Warn if the url isn't set.
     if (!finalUrl) {
-      logger.warn('Missing supabase url, set it either in `nuxt.config.ts` or via env variable')
+      logger.warn('Missing `NUXT_PUBLIC_SUPABASE_URL`, set it in `.env` or via `runtimeConfig.public.supabase.url` in `nuxt.config.ts`.')
     }
     else {
       try {
@@ -206,14 +210,14 @@ export default defineNuxtModule<ModuleOptions>({
 
         // Fail build in production
         if (!nuxt.options.dev) {
-          throw new Error('Invalid Supabase URL configuration')
+          throw new Error(`Invalid Supabase URL: "${finalUrl}". Provide a valid URL or leave it unset for runtime configuration.`)
         }
       }
     }
 
     // Warn if the key isn't set.
     if (!nuxt.options.runtimeConfig.public.supabase.key) {
-      logger.warn('Missing supabase publishable key, set it either in `nuxt.config.ts` or via env variable')
+      logger.warn('Missing `NUXT_PUBLIC_SUPABASE_KEY`, set it in `.env` or via `runtimeConfig.public.supabase.key` in `nuxt.config.ts`.')
     }
 
     // Warn for deprecated features.
@@ -230,7 +234,7 @@ export default defineNuxtModule<ModuleOptions>({
     const hasSecretKey = !!supabaseConfig?.secretKey
 
     if (hasServiceKey && !hasSecretKey) {
-      logger.warn('`SUPABASE_SERVICE_KEY` is deprecated and will be removed in a future version. Please migrate to `SUPABASE_SECRET_KEY` (JWT signing key). See: https://supabase.com/blog/jwt-signing-keys')
+      logger.warn('`SUPABASE_SERVICE_KEY` is deprecated. Migrate to `NUXT_SUPABASE_SECRET_KEY`. See: https://supabase.com/blog/jwt-signing-keys')
     }
 
     // ensure callback URL is not using SSR

src/runtime/server/services/serverSupabaseServiceRole.ts

@@ -17,7 +17,7 @@ export const serverSupabaseServiceRole: <T = Database>(event: H3Event) => Supaba
 
   // Make sure a server key is set
   if (!serverKey) {
-    throw new Error('Missing server key. Set either `SUPABASE_SECRET_KEY` (recommended) or `SUPABASE_SERVICE_KEY` (deprecated) in your environment variables.')
+    throw new Error('Missing server key. Set `NUXT_SUPABASE_SECRET_KEY` in your environment variables.')
   }
 
   // No need to recreate client if exists in request context