Skip to main content

​
Overview

Deriverse uses environment variables to configure blockchain connections, database access, and feature flags. All sensitive configuration should be stored in a .env.local file that is never committed to version control.

​
Setup Instructions

1

Create environment file

Create a .env.local file in your project root:
touch .env.local
2

Add required variables

Copy the required variables below and add your values:
# Supabase Configuration
NEXT_PUBLIC_SUPABASE_URL=your_supabase_project_url
NEXT_PUBLIC_SUPABASE_ANON_KEY=your_supabase_anon_key

# Solana Network Configuration
NEXT_PUBLIC_RPC_HTTP=https://api.devnet.solana.com
3

Restart development server

After adding variables, restart your dev server:
npm run dev

​
Required Variables

These environment variables are required for Deriverse to function properly:

​
Supabase Configuration

​
NEXT_PUBLIC_SUPABASE_URL
string
required
Your Supabase project URL.How to get it:
  1. Go to your Supabase Dashboard
  2. Select your project
  3. Go to Settings → API
  4. Copy the “Project URL”
Example:
NEXT_PUBLIC_SUPABASE_URL=https://abcdefgh.supabase.co
​
NEXT_PUBLIC_SUPABASE_ANON_KEY
string
required
Your Supabase anonymous (public) API key.How to get it:
  1. Go to your Supabase Dashboard
  2. Select your project
  3. Go to Settings → API
  4. Copy the “anon public” key
Example:
NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
This key is safe to use in client-side code. It only allows access based on your Row Level Security (RLS) policies.

​
Solana Network Configuration

​
NEXT_PUBLIC_RPC_HTTP
string
required
Solana RPC endpoint URL for blockchain interactions.Available options:
Use Solana’s public devnet endpoint:
NEXT_PUBLIC_RPC_HTTP=https://api.devnet.solana.com
Recommended for: Local development and testing

​
Optional Variables

These variables are optional and enable additional features:

​
Deriverse Program Configuration

​
NEXT_PUBLIC_PROGRAM_ID
string
The Solana program ID for Deriverse smart contract integration.Default: Drvrseg8AQLP8B96DBGmHRjFGviFNYTkHueY9g3k27Gu (devnet)When to use: Only needed if you’re deploying a custom Deriverse program or using a different network.Example:
NEXT_PUBLIC_PROGRAM_ID=Drvrseg8AQLP8B96DBGmHRjFGviFNYTkHueY9g3k27Gu
​
NEXT_PUBLIC_DERIVERSE_VERSION
string
The version of the Deriverse protocol to use.Default: 12Example:
NEXT_PUBLIC_DERIVERSE_VERSION=12

​
Advanced RPC Configuration

​
NEXT_PUBLIC_HELIUS_RPC_URL
string
Custom Helius RPC endpoint with API key.When to use: If you have a Helius API key for better rate limits and reliability.Example:
NEXT_PUBLIC_HELIUS_RPC_URL=https://devnet.helius-rpc.com/?api-key=your-api-key
​
NEXT_PUBLIC_RPC_DEVNET
string
Override the devnet RPC endpoint.Default: Falls back to NEXT_PUBLIC_HELIUS_RPC_URL or Helius public devnet.Example:
NEXT_PUBLIC_RPC_DEVNET=https://api.devnet.solana.com
​
NEXT_PUBLIC_RPC_MAINNET
string
Override the mainnet RPC endpoint.Default: https://api.mainnet-beta.solana.comExample:
NEXT_PUBLIC_RPC_MAINNET=https://api.mainnet-beta.solana.com
​
NEXT_PUBLIC_WALLET_CLUSTER
string
Set the default wallet cluster.Values:
  • devnet (default)
  • mainnet-beta
Example:
NEXT_PUBLIC_WALLET_CLUSTER=devnet

​
Application Configuration

​
NEXT_PUBLIC_APP_URL
string
The base URL for your application.Default: https://deriverse.appWhen to use: For generating absolute URLs, share links, or Open Graph metadata.Example:
NEXT_PUBLIC_APP_URL=https://deriverse.vercel.app

​
Node Environment

​
NODE_ENV
string
Specifies the Node.js environment.Values:
  • development - Local development (default)
  • production - Production deployment
  • test - Testing environment
Example:
NODE_ENV=development
Next.js automatically sets this during build. You typically don’t need to set this manually.

​
Complete Example

Here’s a complete .env.local example for local development:
.env.local
# Supabase Configuration (Required)
NEXT_PUBLIC_SUPABASE_URL=https://yourproject.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6InlvdXJwcm9qZWN0Iiwicm9sZSI6ImFub24iLCJpYXQiOjE2NDYzODUyMDAsImV4cCI6MTk2MTk2MTIwMH0.example

# Solana Network Configuration (Required)
NEXT_PUBLIC_RPC_HTTP=https://api.devnet.solana.com

# Optional: Advanced Configuration
NEXT_PUBLIC_PROGRAM_ID=Drvrseg8AQLP8B96DBGmHRjFGviFNYTkHueY9g3k27Gu
NEXT_PUBLIC_DERIVERSE_VERSION=12
NEXT_PUBLIC_WALLET_CLUSTER=devnet
NEXT_PUBLIC_APP_URL=http://localhost:3000

# Optional: Helius RPC (Better rate limits)
NEXT_PUBLIC_HELIUS_RPC_URL=https://devnet.helius-rpc.com/?api-key=your-api-key

​
Environment Variable Naming

Variables prefixed with NEXT_PUBLIC_ are exposed to the browser. All other variables are server-side only.
Client-side (Browser) Variables:
  • Must start with NEXT_PUBLIC_
  • Accessible in React components
  • Embedded in the JavaScript bundle
  • Example: NEXT_PUBLIC_SUPABASE_URL
Server-side Only Variables:
  • No special prefix required
  • Only accessible in API routes and server components
  • Never exposed to the browser
  • Example: DATABASE_URL

​
Production Configuration

For production deployments (Vercel, etc.):
1

Set environment variables in your hosting platform

Add all required variables through your platform’s dashboard:
  • Vercel: Project Settings → Environment Variables
  • Netlify: Site Settings → Environment Variables
2

Use production RPC endpoints

Replace devnet endpoints with mainnet:
NEXT_PUBLIC_RPC_HTTP=https://your-production-rpc.com
3

Verify deployment

After deployment, verify all environment variables are loaded:
  • Check browser console for errors
  • Test wallet connections
  • Verify Supabase connectivity
Never commit .env.local, .env.production, or any file containing secrets to version control.

​
Troubleshooting

Possible causes:
  1. Server not restarted: Environment variables are loaded at startup. Restart your dev server: 
    # Stop with Ctrl+C, then:
npm run dev
  2. Wrong file location: Ensure .env.local is in the project root, not in src/ or other subdirectories.
  3. Syntax errors: Check for:
    • Spaces around = (should be KEY=value, not KEY = value)
    • Missing quotes for values with spaces
    • Comments on the same line
  4. Missing NEXT_PUBLIC_ prefix: Client-side variables must have this prefix.
Verify your configuration:
  1. Check URL format: 
    # Correct
NEXT_PUBLIC_SUPABASE_URL=https://project.supabase.co

# Incorrect (missing https://)
NEXT_PUBLIC_SUPABASE_URL=project.supabase.co
  2. Verify anon key: The key should be a long JWT token starting with eyJ.
  3. Check Supabase project status: Ensure your project is active in the Supabase dashboard.
  4. Network access: Some Supabase projects require IP whitelisting.
Common issues:
  1. Rate limiting: Public RPC endpoints have rate limits. Consider using:
  2. Network selection: Ensure you’re using the correct network:
    • Devnet: https://api.devnet.solana.com
    • Mainnet: https://api.mainnet-beta.solana.com
  3. URL format: Must include https:// protocol.

​
Security Best Practices

Never Commit Secrets

Add .env.local to .gitignore to prevent accidentally committing secrets.

Use Different Keys

Use separate Supabase projects and keys for development, staging, and production.

Rotate Keys Regularly

Periodically rotate API keys and update them in your environment configuration.

Limit Permissions

Use Supabase RLS policies to restrict data access based on user authentication.

​
Next Steps

Local Setup

Complete your local development setup

Architecture

Understand how Deriverse components interact

Database Schema

Learn about Supabase database schema

Contributing

Start contributing to Deriverse

Build docs developers (and LLMs) love

Get started for freeTalk to us