Environment Variables

Configure environment variables for Music Store

Overview

Music Store uses environment variables to securely configure the Supabase connection. These variables are loaded at build time using Vite’s environment variable system.

Never commit your .env.local file to version control. It contains sensitive API keys that should remain private.

Required Variables

The application requires two environment variables to connect to Supabase:

VITE_SUPABASE_URL

Description: Your unique Supabase project URL

Format: https://xxxxx.supabase.co

Where to find it:

1. Go to your Supabase Dashboard
2. Select your project
3. Navigate to Settings > API
4. Copy the Project URL

Example:

VITE_SUPABASE_URL=https://abcdefghijklmn.supabase.co

VITE_SUPABASE_KEY

Description: Your Supabase anonymous (public) API key

Format: Long alphanumeric string (JWT token)

Where to find it:

1. Go to your Supabase Dashboard
2. Select your project
3. Navigate to Settings > API
4. Copy the Project API keys > anon public key

Use the anon (public) key, NOT the service_role key. The service role key should never be exposed in frontend code.

Example:

VITE_SUPABASE_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Setup Instructions

1. Create .env.local File

   In the root of your project (same directory as package.json), create a file named .env.local:

   touch .env.local
   

   The file must be named exactly .env.local with the dot prefix. Do not name it env.local or .env.

2. Add Your Variables

   Open .env.local and add your Supabase credentials:

   .env.local

   VITE_SUPABASE_URL=https://your-project-id.supabase.co
   VITE_SUPABASE_KEY=your-anon-public-key-here
   

   Replace the placeholder values with your actual Supabase project URL and anon key from the dashboard.

3. Verify .gitignore

   Ensure .env.local is listed in your .gitignore file:

   .gitignore

   # Local env files
   .env.local
   .env.*.local
   

   This prevents accidentally committing sensitive credentials to version control.

4. Restart Development Server

   After creating or modifying .env.local, restart your development server:

   npm run dev
   

   Vite loads environment variables at startup, so changes require a restart.

How It Works

The Supabase client in backend/supabaseClient.js reads these variables using Vite’s import.meta.env:

backend/supabaseClient.js

import { createClient } from "@supabase/supabase-js";

// Vite exposes variables prefixed with VITE_ via import.meta.env
const supabaseUrl = import.meta.env.VITE_SUPABASE_URL; 
const supabaseKey = import.meta.env.VITE_SUPABASE_KEY; 

// Create and export the Supabase client
export const supabase = createClient(supabaseUrl, supabaseKey);

Vite Requirement: Environment variables must be prefixed with VITE_ to be exposed to client-side code. Variables without this prefix are not accessible.

Environment Variable Naming

Correct

VITE_SUPABASE_URL=...
VITE_SUPABASE_KEY=...
VITE_API_ENDPOINT=...

Incorrect

SUPABASE_URL=...       # Missing VITE_ prefix
Vite_Supabase_Key=...  # Wrong case
REACT_APP_URL=...      # Wrong prefix (CRA syntax)

Security Best Practices

Use the Correct API Key

Always use the anon (public) key in your frontend:

• ✅ anon (public) key - Safe for client-side use, respects Row Level Security
• ❌ service_role key - Full admin access, bypasses all security rules

The service_role key should only be used in secure backend environments, never in frontend code.

Never Commit .env.local

Add .env.local to your .gitignore:

.gitignore

# Environment variables
.env.local
.env.development.local
.env.test.local
.env.production.local

Use a template file like .env.example to document required variables:

.env.example

VITE_SUPABASE_URL=your_supabase_url_here
VITE_SUPABASE_KEY=your_anon_key_here

Rotate Keys if Exposed

If your anon key is accidentally committed:

1. Go to Settings > API in Supabase Dashboard
2. Click Reset API Key (for anon key)
3. Update your .env.local with the new key
4. Restart your dev server

Rotating keys will break any deployed applications using the old key. Update all environments.

Use Row Level Security

Enable RLS on your Supabase tables to control data access:

ALTER TABLE productos ENABLE ROW LEVEL SECURITY;

CREATE POLICY "Public read access"
  ON productos
  FOR SELECT
  TO anon
  USING (true);

This ensures the anon key can only access data as intended, even if exposed.

Deployment

For production deployments, set environment variables in your hosting platform:

Vercel

1. Go to your project settings
2. Navigate to Environment Variables
3. Add:
   • VITE_SUPABASE_URL → your Supabase URL
   • VITE_SUPABASE_KEY → your anon key
4. Redeploy your application

Vercel Environment Variables Docs

Netlify

1. Go to Site settings > Build & deploy
2. Scroll to Environment variables
3. Add:
   • VITE_SUPABASE_URL → your Supabase URL
   • VITE_SUPABASE_KEY → your anon key
4. Trigger a new deploy

Netlify Environment Variables Docs

GitHub Actions

Use repository secrets for CI/CD:

1. Go to Settings > Secrets and variables > Actions
2. Add secrets:
   • VITE_SUPABASE_URL
   • VITE_SUPABASE_KEY
3. Reference in workflow:

.github/workflows/deploy.yml

env:
  VITE_SUPABASE_URL: ${{ secrets.VITE_SUPABASE_URL }}
  VITE_SUPABASE_KEY: ${{ secrets.VITE_SUPABASE_KEY }}

Troubleshooting

Error: supabaseUrl is required

Cause: Environment variables not loaded properly

Solutions:

• Verify file is named exactly .env.local
• Check that variables start with VITE_ prefix
• Restart the dev server (npm run dev)
• Ensure .env.local is in the project root (same level as package.json)

Variables are undefined in code

Cause: Missing VITE_ prefix or server not restarted

Solutions:

• Add VITE_ prefix to all variables
• Stop and restart the development server
• Check for typos in variable names
• Verify you’re using import.meta.env.VITE_* not process.env.*

Connection fails in production

Cause: Environment variables not set in hosting platform

Solutions:

• Add variables to your hosting platform’s environment settings
• Verify variable names match exactly (case-sensitive)
• Trigger a fresh deployment after adding variables
• Check build logs for “undefined” warnings

Invalid API key error

Cause: Wrong key or typo in .env.local

Solutions:

• Copy the key directly from Supabase Dashboard
• Ensure you’re using the anon key, not service_role
• Check for extra spaces or line breaks in the key
• Verify the key corresponds to the correct project URL

Example .env.local File

Here’s a complete example of a properly formatted .env.local file:

.env.local

# Supabase Configuration
# Get these values from: https://app.supabase.com/project/_/settings/api

# Your unique Supabase project URL
VITE_SUPABASE_URL=https://abcdefghijklmn.supabase.co

# Your Supabase anonymous (public) API key
# This is safe to use in client-side code
VITE_SUPABASE_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6ImFiY2RlZmdoaWprbG1uIiwicm9sZSI6ImFub24iLCJpYXQiOjE2ODAwMDAwMDAsImV4cCI6MTk5NTU3NjAwMH0.example_signature_here

The example key above is fake. Replace it with your actual Supabase anon key from your project dashboard.

Next Steps

Supabase Setup

Configure your Supabase project and get your API keys

Quick Start

Run the application locally

Project Structure

Learn where environment variables are used

Deployment

Deploy your application to production