Skip to main content

​
Overview

Cajas requires specific environment variables to connect to your Supabase backend. This guide walks you through setting up your .env.local file with the necessary configuration.

​
Required Environment Variables

The application needs two essential Supabase environment variables:
VariableDescriptionWhere to Find
NEXT_PUBLIC_SUPABASE_URLYour Supabase project URLProject Settings > API
NEXT_PUBLIC_SUPABASE_ANON_KEYPublic anon/client keyProject Settings > API
Both variables are prefixed with NEXT_PUBLIC_ because they need to be accessible in the browser for client-side Supabase connections.

​
Setup Instructions

1

Create Environment File

Create a .env.local file in the root of your project:
touch .env.local
The .env.local file is automatically ignored by git (see .gitignore). Never commit sensitive credentials to version control.
2

Add Supabase Credentials

Open .env.local and add your Supabase project credentials:
.env.local
NEXT_PUBLIC_SUPABASE_URL=https://your-project-id.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key-here
Replace the placeholder values with your actual Supabase project details.
3

Verify Configuration

The environment variables are used in two key files:Client-side usage (lib/supabase/client.ts:5-6):
export function createClient() {
    return createBrowserClient(
        process.env.NEXT_PUBLIC_SUPABASE_URL!,
        process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!
    )
}
Server-side usage (lib/supabase/server.ts:8-9):
return createServerClient(
    process.env.NEXT_PUBLIC_SUPABASE_URL!,
    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
    {
        cookies: {
            // Cookie handling configuration
        }
    }
)
4

Restart Development Server

After adding environment variables, restart your development server:
npm run dev
The server will now load the new environment variables.

​
Environment Files Guide

Cajas follows Next.js environment variable conventions:
  • .env.local - Local development (gitignored)
  • .env.production - Production environment
  • .env.example - Template for required variables (committed to git)
Create a .env.example file with placeholder values to help other developers set up their environment:
.env.example
NEXT_PUBLIC_SUPABASE_URL=https://your-project-id.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key

​
Troubleshooting

​
”Invalid API key” Error

Ensure you’re using the anon (public) key, not the service role key. The service role key should never be exposed to the client.Find it in: Supabase Dashboard > Project Settings > API > anon public
The URL should follow this format:
https://[project-ref].supabase.co
Do not include trailing slashes or additional paths.
Environment variables are loaded at build time. You must restart your development server after changing .env.local:
# Stop the server (Ctrl+C)
npm run dev

​
Environment Variables Not Loading

Ensure .env.local is in the project root directory, at the same level as package.json.
Environment variables should not have quotes or spaces:
# ✅ Correct
NEXT_PUBLIC_SUPABASE_URL=https://example.supabase.co

# ❌ Incorrect
NEXT_PUBLIC_SUPABASE_URL = "https://example.supabase.co"
Sometimes Next.js caches environment variables. Clear the cache and restart:
rm -rf .next
npm run dev

​
Security Best Practices

Never Commit Secrets

Always add .env.local to .gitignore. The project is already configured to ignore .env* files.

Use Anon Key Only

Only use the public anon key in NEXT_PUBLIC_ variables. The service role key should only be used server-side.

Rotate Keys Regularly

Rotate your API keys periodically and immediately if they’re ever exposed.

Environment-Specific Values

Use different Supabase projects for development, staging, and production environments.

​
Next Steps

Supabase Configuration

Set up your Supabase project and enable required services

Database Migrations

Run database migrations to set up your schema

Build docs developers (and LLMs) love

Get started for freeTalk to us