Learning Objectives

Create and configure a Supabase project
Set up environment variables securely
Configure the Supabase client for Next.js
Understand Supabase project structure
Use the Supabase dashboard effectively

1. What is Supabase?

Supabase is an open-source Firebase alternative that provides a complete backend solution. It combines multiple services into a single platform, making it easier to build modern applications without managing separate infrastructure components.

Feature	Description
PostgreSQL Database	Full Postgres database with SQL access
Authentication	Email/password, OAuth, magic links
Realtime	Subscribe to database changes
Storage	File storage with CDN
Edge Functions	Serverless functions at the edge
Row Level Security	Fine-grained access control

Why Supabase for RizPay?

Supabase offers several advantages that make it an excellent choice for building a bill payment platform:

PostgreSQL - Powerful relational database for transactions
Authentication - Built-in auth with security best practices
Row Level Security - Protect user data at database level
Realtime - Live transaction updates
Free Tier - Generous limits for development

2. Creating a Supabase Project

Step 1: Sign Up

Follow these steps to create your Supabase account:

Go to supabase.com
Click "Start your project"
Sign up with GitHub (recommended) or email

Step 2: Create New Project

Once signed in, create a new project by following these steps. Be sure to save your database password in a secure location as it cannot be recovered.

Click "New Project"
Select your organization (or create one)
Fill in project details:
- Name: rizpay or your project name
- Database Password: Generate a strong password (save this!)
- Region: Choose closest to your users
- Pricing Plan: Free tier is fine for development
Click "Create new project"
Wait for setup (usually 2-3 minutes)

Step 3: Get Project Credentials

Navigate to Settings > API and note these credentials. You will need them for your Next.js application configuration.

Project URL: https://your-project-id.supabase.co
Anon/Public Key: For client-side requests
Service Role Key: For server-side admin access (keep secret!)

3. Environment Variables

Create Environment Files

Create two environment files in your project root. The .env.local file contains your actual credentials while .env.example serves as a template for other developers.

# Create environment files
touch .env.local .env.example

Configure Environment Variables

Add your Supabase credentials to the .env.local file. Note the NEXTPUBLIC prefix which determines whether a variable is accessible in the browser.

# .env.local (DO NOT COMMIT - add to .gitignore)

# Supabase Configuration
NEXT_PUBLIC_SUPABASE_URL=https://your-project-id.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key-here

# Server-only (no NEXT_PUBLIC_ prefix)
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key-here

# Database Connection (for direct connections)
DATABASE_URL=postgresql://postgres:[PASSWORD]@db.your-project-id.supabase.co:5432/postgres

Create an example template file that is safe to commit. This helps other developers understand what environment variables are required.

# .env.example (safe to commit - template for other developers)

# Supabase Configuration
NEXT_PUBLIC_SUPABASE_URL=your-supabase-url
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key

# Server-only
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key

# Database Connection
DATABASE_URL=your-database-url

Update .gitignore

Ensure your sensitive environment files are not committed to version control. This prevents accidental exposure of your credentials.

# .gitignore

# Environment files
.env
.env.local
.env.*.local

# Keep example file
!.env.example

Environment Variable Best Practices

Understanding the difference between public and private environment variables is crucial for security. The following table explains when to use each type.

Prefix	Visibility	Use Case
`NEXT_PUBLIC_`	Exposed to browser	Non-sensitive config
No prefix	Server-only	API keys, secrets

This example shows how to access environment variables in your code. Remember that only NEXTPUBLIC prefixed variables are available in client-side code.

// Accessing environment variables

// Client-side (browser) - Only NEXT_PUBLIC_ vars available
const supabaseUrl = process.env.NEXT_PUBLIC_SUPABASE_URL;

// Server-side (API routes, Server Components)
const serviceKey = process.env.SUPABASE_SERVICE_ROLE_KEY;

4. Installing Supabase Client

Install Dependencies

Install the official Supabase packages using your package manager. These packages provide the client SDK and server-side rendering helpers for Next.js.

pnpm add @supabase/supabase-js @supabase/ssr

Package Overview

Each package serves a specific purpose. The core client handles all Supabase interactions while the SSR package provides helpers for Next.js App Router.

Package	Purpose
`@supabase/supabase-js`	Core Supabase client
`@supabase/ssr`	Server-side rendering helpers for Next.js

5. Supabase Client Configuration

Create Utility Files

Organize your Supabase clients in a dedicated folder. Each file creates a client configured for its specific context (browser, server, or middleware).

lib/
├── supabase/
│   ├── client.ts      # Browser client
│   ├── server.ts      # Server client
│   ├── middleware.ts  # Middleware client
│   └── admin.ts       # Admin client (service role)

Browser Client

The browser client is used in Client Components for real-time subscriptions and client-side data fetching. It uses cookies managed by the browser for authentication.

// lib/supabase/client.ts
import { createBrowserClient } from "@supabase/ssr";

export function createClient() {
  return createBrowserClient(
    process.env.NEXT_PUBLIC_SUPABASE_URL!,
    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!
  );
}

// Usage in Client Components
// const supabase = createClient()

Server Client

The server client is used in Server Components and Server Actions. It accesses cookies from the request to maintain the user's authentication state during server-side rendering.

// lib/supabase/server.ts
import { createServerClient } from "@supabase/ssr";
import { cookies } from "next/headers";

export async function createClient() {
  const cookieStore = await cookies();

  return createServerClient(
    process.env.NEXT_PUBLIC_SUPABASE_URL!,
    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
    {
      cookies: {
        getAll() {
          return cookieStore.getAll();
        },
        setAll(cookiesToSet) {
          try {
            cookiesToSet.forEach(({ name, value, options }) =>
              cookieStore.set(name, value, options)
            );
          } catch {
            // Called from Server Component - cookies are read-only
            // This can be ignored if you have middleware refreshing sessions
          }
        },
      },
    }
  );
}

Middleware Client

The middleware client handles session refresh on every request. It ensures that authentication tokens remain valid and updates cookies as needed.

// lib/supabase/middleware.ts
import { createServerClient } from "@supabase/ssr";
import { NextResponse, type NextRequest } from "next/server";

export async function updateSession(request: NextRequest) {
  let supabaseResponse = NextResponse.next({
    request,
  });

  const supabase = createServerClient(
    process.env.NEXT_PUBLIC_SUPABASE_URL!,
    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
    {
      cookies: {
        getAll() {
          return request.cookies.getAll();
        },
        setAll(cookiesToSet) {
          cookiesToSet.forEach(({ name, value, options }) =>
            request.cookies.set(name, value)
          );
          supabaseResponse = NextResponse.next({
            request,
          });
          cookiesToSet.forEach(({ name, value, options }) =>
            supabaseResponse.cookies.set(name, value, options)
          );
        },
      },
    }
  );

  // IMPORTANT: Don't write code between createServerClient and
  // supabase.auth.getUser(). A simple mistake could make your
  // application vulnerable to attacks.
  const {
    data: { user },
  } = await supabase.auth.getUser();

  // Add user check logic here if needed
  // Example: Redirect unauthenticated users from protected routes

  return supabaseResponse;
}

Admin Client (Service Role)

The admin client bypasses Row Level Security and should only be used for administrative operations on the server. Never expose the service role key to the client.

// lib/supabase/admin.ts
import { createClient } from "@supabase/supabase-js";

// WARNING: Only use on the server side!
// This client bypasses Row Level Security

export function createAdminClient() {
  return createClient(
    process.env.NEXT_PUBLIC_SUPABASE_URL!,
    process.env.SUPABASE_SERVICE_ROLE_KEY!,
    {
      auth: {
        autoRefreshToken: false,
        persistSession: false,
      },
    }
  );
}

6. Setting Up Middleware

Create a middleware file in your project root to refresh authentication sessions on each request. The matcher config specifies which routes should be processed.

// middleware.ts (in project root)
import { type NextRequest } from "next/server";
import { updateSession } from "@/lib/supabase/middleware";

export async function middleware(request: NextRequest) {
  return await updateSession(request);
}

export const config = {
  matcher: [
    /*
     * Match all request paths except for:
     * - _next/static (static files)
     * - _next/image (image optimization files)
     * - favicon.ico (favicon file)
     * - public folder
     */
    "/((?!_next/static|_next/image|favicon.ico|.*\\.(?:svg|png|jpg|jpeg|gif|webp)$).*)",
  ],
};

7. TypeScript Types Generation

Install Supabase CLI

The Supabase CLI allows you to generate TypeScript types from your database schema. This provides type safety when querying your database.

# Install globally
npm install -g supabase

# Or use npx
npx supabase --version

Login to Supabase

Authenticate with Supabase to connect the CLI to your project.

supabase login

Generate TypeScript Types

Run this command to generate types based on your database tables. The output file provides interfaces for all your tables, including Row, Insert, and Update types.

# Generate types from your Supabase project
supabase gen types typescript --project-id your-project-id > lib/supabase/database.types.ts

Using Generated Types

The generated types file defines interfaces for your database schema. These types include Row (for reading), Insert (for creating), and Update (for modifying) variations for each table.

// lib/supabase/database.types.ts (auto-generated)
export type Json =
  | string
  | number
  | boolean
  | null
  | { [key: string]: Json | undefined }
  | Json[];

export interface Database {
  public: {
    Tables: {
      users: {
        Row: {
          id: string;
          email: string;
          full_name: string;
          created_at: string;
        };
        Insert: {
          id?: string;
          email: string;
          full_name: string;
          created_at?: string;
        };
        Update: {
          id?: string;
          email?: string;
          full_name?: string;
          created_at?: string;
        };
      };
      // ... more tables
    };
  };
}

Type-Safe Client

Pass the Database type to your client creation function to enable full type checking on all queries. This catches errors at compile time rather than runtime.

// lib/supabase/client.ts
import { createBrowserClient } from "@supabase/ssr";
import { Database } from "./database.types";

export function createClient() {
  return createBrowserClient<Database>(
    process.env.NEXT_PUBLIC_SUPABASE_URL!,
    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!
  );
}

8. Supabase Dashboard Overview

Key Dashboard Sections

The Supabase dashboard provides a comprehensive interface for managing your project. Familiarize yourself with these key sections to work efficiently.

Section	Purpose
Table Editor	Visual database management
SQL Editor	Run raw SQL queries
Authentication	Manage users and auth settings
Storage	Manage file buckets
Edge Functions	Deploy serverless functions
Database	Roles, extensions, backups
Settings	API keys, project settings

Using the SQL Editor

The SQL Editor allows you to run queries directly against your database. This is useful for creating tables, testing queries, and setting up Row Level Security policies.

-- Run queries directly in dashboard
SELECT * FROM users LIMIT 10;

-- Create tables
CREATE TABLE IF NOT EXISTS profiles (
  id UUID PRIMARY KEY REFERENCES auth.users(id),
  full_name TEXT,
  avatar_url TEXT,
  updated_at TIMESTAMPTZ DEFAULT NOW()
);

-- Enable RLS
ALTER TABLE profiles ENABLE ROW LEVEL SECURITY;

9. Project Structure Best Practices

Recommended File Structure

Organizing your files in a consistent structure makes your project easier to navigate and maintain. Keep Supabase-related utilities together in the lib folder.

project/
├── app/
│   ├── (auth)/
│   │   ├── login/
│   │   └── register/
│   ├── (dashboard)/
│   │   ├── layout.tsx
│   │   └── page.tsx
│   └── api/
├── lib/
│   ├── supabase/
│   │   ├── client.ts
│   │   ├── server.ts
│   │   ├── middleware.ts
│   │   ├── admin.ts
│   │   └── database.types.ts
│   └── utils.ts
├── middleware.ts
├── .env.local
├── .env.example
└── package.json

Environment Check Helper

Create a helper function to validate that all required environment variables are present. This catches configuration errors early during development.

// lib/supabase/check-env.ts
export function checkSupabaseEnv() {
  const requiredEnvVars = [
    "NEXT_PUBLIC_SUPABASE_URL",
    "NEXT_PUBLIC_SUPABASE_ANON_KEY",
  ];

  const missing = requiredEnvVars.filter((envVar) => !process.env[envVar]);

  if (missing.length > 0) {
    throw new Error(
      `Missing required environment variables: ${missing.join(", ")}`
    );
  }
}

// Call in your app initialization

10. Verifying Setup

Test Connection Script

Create a test script to verify your Supabase connection is working correctly. This script attempts a simple database operation and reports the result.

// scripts/test-supabase.ts
import { createClient } from "@supabase/supabase-js";

const supabase = createClient(
  process.env.NEXT_PUBLIC_SUPABASE_URL!,
  process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!
);

async function testConnection() {
  try {
    const { data, error } = await supabase
      .from("_test_connection")
      .select("*")
      .limit(1);

    if (error && error.code !== "PGRST116") {
      // PGRST116 = table doesn't exist (which is fine for a test)
      console.error("Connection error:", error);
      return false;
    }

    console.log("Supabase connection successful!");
    return true;
  } catch (err) {
    console.error("Failed to connect:", err);
    return false;
  }
}

testConnection();

Test in a Page Component

Create a test page to verify both authentication and database connectivity from within your Next.js application. This confirms that all the client configurations are working.

// app/test-supabase/page.tsx
import { createClient } from '@/lib/supabase/server'

export default async function TestPage() {
  const supabase = await createClient()

  // Test auth
  const { data: { user } } = await supabase.auth.getUser()

  // Test database (if you have tables)
  // const { data, error } = await supabase.from('your_table').select('*').limit(1)

  return (
    <div className="p-8">
      <h1 className="text-2xl font-bold mb-4">Supabase Connection Test</h1>
      <div className="space-y-2">
        <p>
          <strong>Status:</strong>{' '}
          <span className="text-green-600">Connected</span>
        </p>
        <p>
          <strong>User:</strong> {user ? user.email : 'Not logged in'}
        </p>
      </div>
    </div>
  )
}

Additional Resources

Next Lesson: Database Schema Design