NxSupabase

The official Nx plugin for Supabase

Automated migrations, type generation, and local dev setup for Nx monorepos.

Getting Started · Features · Documentation · Contributing

Building modern applications with Supabase in an Nx monorepo? This plugin streamlines your entire workflow:

• Zero Configuration - Auto-detect Supabase projects via config.toml
• Smart Port Management - Run multiple Supabase instances without conflicts
• Nx Caching - Generated types are cached and only regenerated when needed
• Full Lifecycle Support - From local dev to production deployment

Before you begin, ensure you have:

• Node.js 18+ installed
• Docker Desktop installed and running
• Supabase CLI installed:

# Via npm
npm install -g supabase

# Or via Homebrew (macOS)
brew install supabase/tap/supabase

npm install @nxsupabase/supabase --save-dev

nx g @nxsupabase/supabase:init

This registers the plugin in your nx.json and configures target defaults.

Run the generator and follow the interactive prompts:

nx g @nxsupabase/supabase:project

All generators support interactive prompts - just run the command without flags and you'll be guided through the options.

This creates the Supabase directory structure:

apps/my-app/
└── supabase/
    ├── config.toml          # Supabase configuration
    ├── migrations/          # Database migrations
    ├── functions/           # Edge Functions
    └── seed.sql             # Seed data

nx run my-app:supabase-start

This spins up the full Supabase stack locally (PostgreSQL, Auth, Storage, Realtime, etc.)

nx g @nxsupabase/supabase:migration --project=my-app --name=create_users_table

nx run my-app:supabase-gen-types

Types are automatically cached by Nx and regenerated only when migrations change.

Run multiple Supabase instances in your monorepo:

# Start all Supabase instances
nx run-many -t supabase-start

# Generate types for all projects
nx run-many -t supabase-gen-types

# Only affected projects
nx affected -t supabase-db-reset

Configure the plugin in nx.json:

{
  "plugins": [
    {
      "plugin": "@nxsupabase/supabase",
      "options": {
        "startTargetName": "supabase-start",
        "stopTargetName": "supabase-stop",
        "genTypesTargetName": "supabase-gen-types"
      }
    }
  ]
}

The plugin loads environment variables from (in order):

1. Workspace root .env
2. Workspace root .env.local
3. Project .env
4. Project .env.local

Common variables:

import { createClient } from '@supabase/supabase-js';
import type { Database } from './types/supabase';

const supabase = createClient<Database>(
  process.env.SUPABASE_URL!,
  process.env.SUPABASE_ANON_KEY!
);

// Fully typed queries
const { data: users } = await supabase
  .from('users')
  .select('id, email, created_at')
  .eq('active', true);

// TypeScript knows the shape of `users`

nx g @nxsupabase/supabase:function --project=my-app --name=send-email --template=basic

// supabase/functions/send-email/index.ts
import { serve } from 'https://deno.land/[email protected]/http/server.ts';

serve(async (req) => {
  const { to, subject, body } = await req.json();

  // Your email logic here

  return new Response(JSON.stringify({ success: true }), {
    headers: { 'Content-Type': 'application/json' },
  });
});

# Link to your Supabase project
npx supabase link --project-ref your-project-ref

# Deploy everything
nx run my-app:supabase-deploy

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

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

This project is licensed under the MIT License - see the LICENSE file for details.