@gridatek/nx-supabase

Features

✨ Multi-Environment Support - Manage production, local, staging, and custom environments

🔧 Convention Over Configuration - Automatic project detection via inferred tasks plugin

🚀 Simple Workflows - Easy-to-use generators and executors for common Supabase operations

📦 Monorepo Ready - Built specifically for Nx workspaces

🔄 Environment Merging - Base configuration with environment-specific overrides

⚡ Fast Builds - Intelligent caching and optimized build process

Quick Start

Installation

# Add the plugin to your Nx workspace
npx nx add @gridatek/nx-supabase

This command will:

• Install the @gridatek/nx-supabase package
• Add Supabase CLI to your devDependencies
• Register the plugin in your nx.json

Create Your First Supabase Project

# Generate a new Supabase project (defaults to project name as directory in the root)
npx nx g @gridatek/nx-supabase:project my-supabase
# Creates at: my-supabase/ (in the root)

# Custom directory (project name ≠ folder name)
npx nx g @gridatek/nx-supabase:project my-supabase --directory=apps/my-api/supabase
# Creates at: apps/my-api/supabase/
# Run with: nx run my-supabase:start

# Or match folder name to project name
npx nx g @gridatek/nx-supabase:project my-supabase --directory=apps/my-api/my-supabase
# Creates at: apps/my-api/my-supabase/

This creates a project with:

• production/ - Your production configuration (base for all environments)
• local/ - Local development overrides
• .generated/ - Auto-generated build outputs
• project.json - Nx project configuration (optional with --skipProjectJson)

Start Using Supabase

# Build environment configurations
npx nx run my-supabase:build

# Start Supabase locally (defaults to 'local' environment)
npx nx run my-supabase:start

# Check status
npx nx run my-supabase:run-command --command="supabase status"

# Stop Supabase
npx nx run my-supabase:stop

Project Structure

my-supabase/
├── production/              # Production environment (base configuration)
│   ├── config.toml          # Main Supabase configuration
│   ├── migrations/          # Production migrations
│   │   └── 001_init.sql
│   └── seeds/               # Production seed data
│       └── data.sql
├── local/                   # Local development overrides
│   ├── migrations/          # Local-only migrations (optional)
│   └── seeds/               # Local-only seed data (optional)
├── .generated/              # AUTO-GENERATED (do not edit)
│   └── local/               # Built local config (production + local overrides)
├── .gitignore               # Ignores .generated/
├── README.md                # Project documentation
└── project.json             # Nx targets (optional with inferred tasks)

How It Works

Environment Architecture

1. Production Directory: Serves as both the base configuration AND the production environment. Used directly without copying.

2. Additional Environments: Each environment (local, staging, etc.) starts with the production config and merges in environment-specific overrides.

3. Build Process:

   • Production: Used directly from production/ folder
   • Other environments: Built to .generated/<env> by merging production + environment-specific files

Automatic Project Detection

Projects are automatically detected when you have a production/config.toml file. The plugin extracts the project name from the project_id field in config.toml.

Available Commands

Generators

project - Create a new Supabase project

# Basic usage
npx nx g @gridatek/nx-supabase:project <name>

# With options
npx nx g @gridatek/nx-supabase:project my-supabase \
  --directory=apps/my-api/supabase \
  --environments=staging,qa \
  --skipProjectJson
# Creates at: apps/my-api/supabase/

Options:

• --directory - Directory where the project will be created (defaults to project name)
• --environments - Comma-separated list of additional environments (beyond production and local)
• --skipProjectJson - Skip creating project.json, rely on inferred tasks plugin

Default Environments: Production and local are always created. Use --environments to add more like staging, qa, dev, etc.

init - Initialize the plugin (runs automatically via nx add)

npx nx g @gridatek/nx-supabase:init

Executors

build - Build environment configurations

npx nx run <project>:build

Merges production config with environment-specific files and outputs to .generated/ (except production which is used directly).

start - Start Supabase

# Default environment (local)
npx nx run <project>:start

# Specific environment
npx nx run <project>:start --env=production

Automatically runs build before starting.

stop - Stop Supabase

npx nx run <project>:stop

Stops the running Supabase instance.

run-command - Run any Supabase CLI command

# Check status
npx nx run <project>:run-command --command="supabase status"

# Create migration
npx nx run <project>:run-command --command="supabase migration new my_table"

# Reset database
npx nx run <project>:run-command --env=local --command="supabase db reset"

# Generate types
npx nx run <project>:run-command --command="supabase gen types typescript --local"

Multiple Environments

Creating Additional Environments

npx nx g @gridatek/nx-supabase:project my-supabase \
  --directory=apps/my-api/supabase \
  --environments=staging,qa,dev
# Creates at: apps/my-api/supabase/

This creates:

• production/ (base config, always created)
• local/ (always created)
• staging/ (additional)
• qa/ (additional)
• dev/ (additional)

Working with Environments

# Build all environments
npx nx run my-api:build

# Start with staging environment
npx nx run my-api:start --env=staging

# Run command in QA environment
npx nx run my-api:run-command --env=qa --command="supabase status"

Environment Override Strategy

1. Start with production config as base
2. Override with environment-specific files
3. Files in environment directories take precedence

Example:

• production/config.toml - Base config for all environments
• staging/config.toml - Overrides only the settings different in staging
• Result: .generated/staging/ contains merged configuration

Inferred Tasks (Optional)

By default, projects include a project.json with explicit targets. You can skip this file and rely entirely on the inferred tasks plugin:

npx nx g @gridatek/nx-supabase:project my-api --skipProjectJson

Benefits:

• Less configuration to maintain
• Automatic task detection
• Convention over configuration
• Projects detected by production/config.toml presence

The plugin automatically infers these targets:

• build - Build environment configurations
• start - Start Supabase
• stop - Stop Supabase
• run-command - Run any Supabase command

Examples

Common Workflows

Setting up a new project

# 1. Generate project
npx nx g @gridatek/nx-supabase:project my-app

# 2. Start locally
npx nx run my-app:start

# 3. Check it's running
npx nx run my-app:run-command --command="supabase status"

# 4. Create a migration
npx nx run my-app:run-command --command="supabase migration new create_users_table"

# 5. Stop when done
npx nx run my-app:stop

Working with multiple projects

# Start multiple projects in parallel
npx nx run-many --target=start --projects=api,admin

# Build all Supabase projects
npx nx run-many --target=build --all

# Stop all
npx nx run-many --target=stop --all

Environment-specific migrations

# Local-only test migration
# 1. Create in local/migrations/
# 2. Build to apply
npx nx run my-app:build

# 3. Start with local environment (default)
npx nx run my-app:start

Configuration

Plugin Options (nx.json)

{
  "plugins": [
    {
      "plugin": "@gridatek/nx-supabase",
      "options": {
        "buildTargetName": "build",
        "startTargetName": "start",
        "stopTargetName": "stop",
        "runCommandTargetName": "run-command"
      }
    }
  ]
}

Supabase Configuration

Edit production/config.toml for base configuration. See Supabase CLI documentation for available options.

CI/CD Integration

GitHub Actions Example

name: CI

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: 20

      - name: Install dependencies
        run: npm ci

      - name: Build Supabase projects
        run: npx nx run-many --target=build --all

      - name: Start Supabase
        run: npx nx run my-app:start

      - name: Run migrations
        run: npx nx run my-app:run-command --command="supabase db reset"

      - name: Run tests
        run: npm test

      - name: Stop Supabase
        run: npx nx run my-app:stop

Documentation

• 📖 API Reference - Detailed API documentation
• 🎯 Best Practices - Recommended patterns and workflows
• 🔧 Advanced Usage - Complex scenarios and customization
• 🚀 Migration Guide - Migrating existing Supabase projects

Requirements

• Node.js 18+
• Nx 22+
• Docker (for running Supabase locally)

Contributing

Contributions are welcome! Please read our contributing guidelines before submitting a PR.

Development Setup

# Clone the repository
git clone https://github.com/gridatek/nx-supabase.git
cd nx-supabase

# Install dependencies
npm install

# Run tests
npx nx test nx-supabase

# Build the plugin
npx nx build nx-supabase

# Run e2e tests
npx nx e2e e2e

License

MIT © GridaTek

Support

• 🐛 Report Issues
• 💬 Discussions
• 📧 Email Support

Acknowledgments

• Built on top of Nx and Supabase
• Inspired by the Nx community's excellent plugins