supabase-install-authClaude Skill

Supabase Install & Auth

Overview

Install the Supabase SDK, CLI, and project credentials from scratch — covering package install, environment configuration, client initialization, and connection verification for both TypeScript (@supabase/supabase-js) and Python (supabase).

Key facts:

• npm package: @supabase/supabase-js
• Python package: supabase (via pip)
• Client factory: createClient() — never new SupabaseClient()
• Dashboard: https://supabase.com/dashboard (Settings > API for keys)
• Docs: https://supabase.com/docs

Prerequisites

• Node.js 18+ (for JS/TS) or Python 3.8+ (for Python)
• Package manager: npm, pnpm, or yarn (JS) / pip (Python)
• A Supabase project created at https://supabase.com/dashboard
• Docker Desktop (only if using local development via supabase start)

Instructions

Step 1 — Install the SDK and CLI

Install the SDK and the Supabase CLI:

JavaScript / TypeScript:

# Install the SDK
npm install @supabase/supabase-js

# For SSR frameworks (Next.js, SvelteKit, Nuxt), also install:
npm install @supabase/ssr

# Install the Supabase CLI (for types, migrations, local dev)
npm install -D supabase

Python:

# Install the SDK
pip install supabase

# Install the CLI (alternative: brew install supabase/tap/supabase)
npm install -g supabase

Verify the CLI is available:

npx supabase --version

Step 2 — Configure Environment Variables

Retrieve project credentials from the Supabase Dashboard (Settings > API) and create the env file:

# .env.local (or .env)
SUPABASE_URL=https://<project-ref>.supabase.co
SUPABASE_KEY=eyJhbGciOiJIUzI1NiIs...          # anon key — safe for client-side
SUPABASE_SERVICE_ROLE_KEY=eyJhbGciOiJIUzI1...  # admin key — server-side ONLY

Add env files to .gitignore immediately:

.env
.env.local
.env.*.local

Security rules:

• The anon key (SUPABASE_KEY) is safe for client-side code. It respects Row Level Security (RLS) policies.
• The service role key (SUPABASE_SERVICE_ROLE_KEY) bypasses RLS entirely. Use only on the server. Never bundle into client code or expose in browser.

Step 3 — Initialize the Client and Verify

Create a client singleton and verify connectivity:

TypeScript — client-side (anon key):

// lib/supabase.ts
import { createClient } from '@supabase/supabase-js'

const supabase = createClient(
  process.env.SUPABASE_URL!,
  process.env.SUPABASE_KEY!
)

export default supabase

TypeScript — server-side (service role key):

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

export const supabaseAdmin = createClient(
  process.env.SUPABASE_URL!,
  process.env.SUPABASE_SERVICE_ROLE_KEY!,
  {
    auth: {
      autoRefreshToken: false,
      persistSession: false,
    },
  }
)

Python — client initialization:

# lib/supabase_client.py
import os
from supabase import create_client

url = os.environ["SUPABASE_URL"]
key = os.environ["SUPABASE_KEY"]

supabase = create_client(url, key)

Verify the connection:

// Quick connectivity check
const { data, error } = await supabase.from('_health_check').select('*').limit(1)
if (error && error.code !== 'PGRST116') {
  // PGRST116 = relation does not exist (expected if table doesn't exist yet)
  throw new Error(`Supabase connection failed: ${error.message}`)
}
console.log('Supabase connected successfully')

Optional — generate TypeScript types from the database schema:

npx supabase login
npx supabase link --project-ref <your-project-ref>
npx supabase gen types typescript --linked > lib/database.types.ts

Then add the type parameter to the client:

import type { Database } from './database.types'
const supabase = createClient<Database>(url, key)

Output

Completing all three steps produces:

• @supabase/supabase-js or supabase Python package installed
• Supabase CLI available via npx supabase
• .env.local containing SUPABASE_URL, SUPABASE_KEY, and SUPABASE_SERVICE_ROLE_KEY
• Client singleton module (lib/supabase.ts or lib/supabase_client.py)
• Server-side admin client (lib/supabase-admin.ts, TypeScript only)
• Verified connectivity to the Supabase project

Error Handling

Error	Cause	Fix
FetchError: request failed	Wrong SUPABASE_URL	Verify URL at Dashboard > Settings > API
Invalid API key	Wrong or expired key	Copy fresh anon key from Dashboard > Settings > API
PGRST301: JWSError	Malformed JWT in key	Remove trailing whitespace/newlines from env var
Cannot find module '@supabase/supabase-js'	SDK not installed	Run npm install @supabase/supabase-js
ModuleNotFoundError: No module named 'supabase'	Python SDK not installed	Run pip install supabase
supabase: command not found	CLI not installed	Run npm install -D supabase, then use npx supabase
Error: supabase start fails	Docker not running	Start Docker Desktop, then retry npx supabase start
TypeError: SupabaseClient is not a constructor	Wrong import pattern	Use createClient() — not new SupabaseClient()

Examples

Full TypeScript and Python examples with auth sign-up, sign-in, session management, SSR patterns, and type-safe queries: examples

Resources

• Supabase JS Client Reference — createClient options, auth, database, storage, realtime
• Supabase Python Client Reference — Python SDK setup and usage
• Supabase CLI Reference — local dev, migrations, type generation
• Supabase Auth Guide — email/password, OAuth, magic links, RLS
• Generating TypeScript Types — type-safe database queries
• Supabase Dashboard — project settings, API keys, database editor

Next Steps

After successful setup, continue with:

• supabase-hello-world — run your first database query
• supabase-rls-policies — secure your tables with Row Level Security
• supabase-email-auth — set up email/password authentication flows