playbooks

home / skills / jeremylongshore / claude-code-plugins-plus-skills / supabase-multi-env-setup

supabase-multi-env-setup skill

/plugins/saas-packs/supabase-pack/skills/supabase-multi-env-setup

This skill helps configure Supabase across development, staging, and production by managing per environment secrets and safeguards.

npx playbooks add skill jeremylongshore/claude-code-plugins-plus-skills --skill supabase-multi-env-setup

Review the files below or copy the command above to add this skill to your agents.

Files (4)
SKILL.md
1.6 KB
---
name: supabase-multi-env-setup
description: |
  Configure Supabase across development, staging, and production environments.
  Use when setting up multi-environment deployments, configuring per-environment secrets,
  or implementing environment-specific Supabase configurations.
  Trigger with phrases like "supabase environments", "supabase staging",
  "supabase dev prod", "supabase environment setup", "supabase config by env".
allowed-tools: Read, Write, Edit, Bash(aws:*), Bash(gcloud:*), Bash(vault:*)
version: 1.0.0
license: MIT
author: Jeremy Longshore <[email protected]>
---

# Supabase Multi Env Setup

## Prerequisites
- Separate Supabase accounts or API keys per environment
- Secret management solution (Vault, AWS Secrets Manager, etc.)
- CI/CD pipeline with environment variables
- Environment detection in application

## Instructions

### Step 1: Create Config Structure
Set up the base and per-environment configuration files.

### Step 2: Implement Environment Detection
Add logic to detect and load environment-specific config.

### Step 3: Configure Secrets
Store API keys securely using your secret management solution.

### Step 4: Add Environment Guards
Implement safeguards for production-only operations.

## Output
- Multi-environment config structure
- Environment detection logic
- Secure secret management
- Production safeguards enabled

## Error Handling

See `{baseDir}/references/errors.md` for comprehensive error handling.

## Examples

See `{baseDir}/references/examples.md` for detailed examples.

## Resources
- [Supabase Environments Guide](https://supabase.com/docs/environments)
- [12-Factor App Config](https://12factor.net/config)

Overview

This skill configures Supabase across development, staging, and production environments to enforce safe, repeatable deployments. It creates a clear config structure, integrates secret management, and adds environment guards so operations behave correctly per environment. Use it to centralize Supabase connection logic and reduce runtime mistakes.

How this skill works

The skill generates a base configuration and environment-specific overrides, then injects detection logic so the application loads the correct settings at runtime. It integrates recommended secret management (Vault, AWS Secrets Manager, or CI secrets) to prevent embedding keys in code. Finally, it inserts production-only guards and CI/CD checks to avoid accidental destructive operations in non-production environments.

When to use it

  • Setting up separate Supabase instances for dev, staging, and prod
  • Implementing per-environment API keys and database URLs
  • Preparing a CI/CD pipeline that deploys to multiple environments
  • Adding runtime checks to prevent production data mishaps
  • Centralizing environment configs for microservices or multi-repo projects

Best practices

  • Store all secrets in a dedicated secrets manager and reference them via environment variables in CI/CD
  • Keep a minimal base config and apply small, explicit overrides per environment
  • Implement runtime environment detection (NODE_ENV or custom env var) and fail fast on unknown environments
  • Add production-only confirmation steps for destructive tasks like migrations or data resets
  • Version control non-secret config files and document environment differences in a single place

Example use cases

  • Local development uses a lightweight Supabase project while CI deploys to staging and production keys
  • A migration job runs only in staging and production, guarded by an explicit PROD flag
  • A microservice reads a shared base config and merges in environment overrides from secure storage
  • CI/CD pipeline injects appropriate Supabase keys per environment and runs environment-specific tests
  • Rollback-safe deploys where production changes require manual approval before applying schema updates

FAQ

How should I detect the current environment at runtime?

Use a dedicated environment variable (e.g., APP_ENV) with allowed values (development, staging, production) and validate it on startup; fail fast if it is missing or invalid.

Where do I store Supabase keys?

Keep keys in a secrets manager (Vault, AWS Secrets Manager, GitHub Actions secrets) and inject them into the runtime via CI/CD environment variables rather than committing them to code.

What production safeguards are recommended?

Require an explicit production flag for migrations and destructive scripts, add CI approvals for production deploys, and log attempts to run production-only actions.