---
name: supabase-auth-storage-realtime-core
description: 'Implement Supabase Auth (signUp, signIn, OAuth, session management), Storage (upload, download, signed URLs, bucket policies), and Realtime (Postgres changes, broadcast, presence). Use when building user auth flows, file upload features, or live-updating UIs with Supabase. Trigger with phrases like "supabase auth", "supabase storage upload", "supabase realtime subscribe", "supabase oauth", "supabase file upload", "supabase presence", "supabase rls storage".'
allowed-tools: Read, Write, Edit, Bash(npm:*), Bash(supabase:*), Grep
version: 1.55.0
license: MIT
author: Jeremy Longshore <jeremy@intentsolutions.io>
tags:
  - saas
  - supabase
  - auth
  - storage
  - realtime
  - rls
compatibility: Designed for Claude Code
title: supabase-auth-storage-realtime-core
canonical_url: https://skilld.dev/gh/jeremylongshore/tons-of-skills-marketplace/supabase-auth-storage-realtime-core
last_updated: 2026-11-01T03:01:42.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> Supporting files, fetch one when the Skill refers to it: [references/auth.md](https://skilld.dev/api/skills-raw/jeremylongshore/tons-of-skills-marketplace/supabase-auth-storage-realtime-core/references/auth.md), [references/examples.md](https://skilld.dev/api/skills-raw/jeremylongshore/tons-of-skills-marketplace/supabase-auth-storage-realtime-core/references/examples.md), [references/python-examples.md](https://skilld.dev/api/skills-raw/jeremylongshore/tons-of-skills-marketplace/supabase-auth-storage-realtime-core/references/python-examples.md), [references/realtime.md](https://skilld.dev/api/skills-raw/jeremylongshore/tons-of-skills-marketplace/supabase-auth-storage-realtime-core/references/realtime.md), [references/storage.md](https://skilld.dev/api/skills-raw/jeremylongshore/tons-of-skills-marketplace/supabase-auth-storage-realtime-core/references/storage.md).
>
> If the user asked to install this Skill, run `npx skilld install jeremylongshore/tons-of-skills-marketplace/supabase-auth-storage-realtime-core`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/supabase-auth-storage-realtime-core`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/jeremylongshore/tons-of-skills-marketplace/supabase-auth-storage-realtime-core) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/supabase-auth-storage-realtime-core`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/supabase-auth-storage-realtime-core --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/supabase-auth-storage-realtime-core --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# Supabase Auth + Storage + Realtime Core

## Overview

Implement the three pillars that turn a Supabase database into a full application backend: user authentication (email/password, OAuth, magic links, session lifecycle), file storage (uploads, downloads, signed URLs, bucket-level RLS policies), and real-time subscriptions (Postgres change events, client-to-client broadcast, presence tracking). Every operation integrates with Row-Level Security through `auth.uid()`.

Each pillar below carries a lean skeleton in this file; the full, copy-paste walkthroughs live in `references/` so this file stays scannable.

## Prerequisites

- Supabase project created at [supabase.com/dashboard](https://supabase.com/dashboard)
- `@supabase/supabase-js` v2 installed (`npm install @supabase/supabase-js`)
- `SUPABASE_URL` and `SUPABASE_ANON_KEY` available from project Settings > API
- For Python: `pip install supabase` (wraps `postgrest-py`, `gotrue-py`, `storage3`, `realtime-py`)

## Instructions

Read the file (Read), edit or create the client and route/component code (Write, Edit), and grep the project (Grep) to reuse an existing Supabase client before creating a new one. Use `Bash(npm:*)` to install the SDK and `Bash(supabase:*)` to run migrations/policies.

### Step 1: Auth — registration, login, OAuth

Initialize the client once, then wire the flows your app needs. The skeleton:

```typescript
import { createClient } from '@supabase/supabase-js'

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

// Email/password
await supabase.auth.signUp({ email, password })
await supabase.auth.signInWithPassword({ email, password })

// OAuth — redirect the user to data.url
const { data } = await supabase.auth.signInWithOAuth({ provider: 'google' })

// React to session changes (SIGNED_IN / SIGNED_OUT / TOKEN_REFRESHED)
supabase.auth.onAuthStateChange((event, session) => { /* update UI */ })
```

Full auth walkthrough — OAuth callback, magic link, session lifecycle, password reset: [references/auth.md](https://skilld.dev/api/skills-raw/jeremylongshore/tons-of-skills-marketplace/supabase-auth-storage-realtime-core/references/auth.md). Python: [references/python-examples.md](https://skilld.dev/api/skills-raw/jeremylongshore/tons-of-skills-marketplace/supabase-auth-storage-realtime-core/references/python-examples.md).

### Step 2: Storage — upload, download, secure with bucket policies

Public buckets serve via CDN URLs; private buckets require signed URLs. The skeleton:

```typescript
// Upload to the signed-in user's own folder (RLS enforces ownership)
await supabase.storage.from('avatars').upload(`${userId}/avatar.png`, file, { upsert: true })

// Public URL (public bucket) vs. time-limited signed URL (private bucket)
supabase.storage.from('avatars').getPublicUrl(`${userId}/avatar.png`)
await supabase.storage.from('documents').createSignedUrl('reports/q4.pdf', 3600)
```

Full storage walkthrough — download, list, delete, and the bucket RLS policies that enforce per-user access: [references/storage.md](https://skilld.dev/api/skills-raw/jeremylongshore/tons-of-skills-marketplace/supabase-auth-storage-realtime-core/references/storage.md). Python: [references/python-examples.md](https://skilld.dev/api/skills-raw/jeremylongshore/tons-of-skills-marketplace/supabase-auth-storage-realtime-core/references/python-examples.md).

### Step 3: Realtime — Postgres changes, broadcast, presence

Three channel types: database change listeners, client-to-client broadcast, and presence. The skeleton:

```typescript
const channel = supabase
  .channel('chat-room')
  .on('postgres_changes',
    { event: 'INSERT', schema: 'public', table: 'messages' },
    (payload) => console.log('New:', payload.new))
  .subscribe()
// One-time table setup: ALTER PUBLICATION supabase_realtime ADD TABLE messages;
supabase.removeChannel(channel)  // clean up
```

Full realtime walkthrough — UPDATE/DELETE filters, RLS-scoped subscriptions, broadcast, and presence tracking: [references/realtime.md](https://skilld.dev/api/skills-raw/jeremylongshore/tons-of-skills-marketplace/supabase-auth-storage-realtime-core/references/realtime.md). Python: [references/python-examples.md](https://skilld.dev/api/skills-raw/jeremylongshore/tons-of-skills-marketplace/supabase-auth-storage-realtime-core/references/python-examples.md).

## Output

- Auth: user registration, password login, OAuth flow (Google/GitHub), magic link, session lifecycle with `onAuthStateChange`, password reset
- Storage: file upload/download, public URLs for CDN-served assets, time-limited signed URLs for private files, bucket-level RLS policies using `auth.uid()` and `storage.foldername()`
- Realtime: Postgres change subscriptions with server-side filters, broadcast channels for client-to-client messaging, presence tracking for online status

## Error Handling

| Error | Cause | Solution |
| ------- | ------- | ---------- |
| `AuthApiError: User already registered` | Duplicate email signup | Use `signInWithPassword` or check existence first |
| `AuthApiError: Invalid login credentials` | Wrong email or password | Verify credentials; check email confirmation status |
| `AuthApiError: Email not confirmed` | User has not clicked confirmation link | Resend with `resend({ type: 'signup', email })` |
| `StorageApiError: Bucket not found` | Bucket does not exist | Create via dashboard or `INSERT INTO storage.buckets` |
| `StorageApiError: new row violates row-level security` | RLS policy blocking the operation | Verify `storage.objects` policies match the user and bucket |
| `StorageApiError: The resource already exists` | File exists and `upsert: false` | Set `upsert: true` to overwrite or use a unique path |
| `Realtime: channel error` or `TIMED_OUT` | Network issues or Realtime not enabled | Check `ALTER PUBLICATION supabase_realtime ADD TABLE` for the target table |
| `Realtime: too many channels` | Exceeded concurrent channel limit | Unsubscribe unused channels with `removeChannel()` |

## Examples

The end-to-end flow — sign in, upload an avatar to the user's RLS-guarded folder, resolve its public URL, and subscribe to live profile updates — is in [references/examples.md](https://skilld.dev/api/skills-raw/jeremylongshore/tons-of-skills-marketplace/supabase-auth-storage-realtime-core/references/examples.md). Each step composes the three skeletons above with no new API surface.

## Resources

- [Auth Guide](https://supabase.com/docs/guides/auth)
- [Auth API Reference](https://supabase.com/docs/reference/javascript/auth-signup)
- [Storage Guide](https://supabase.com/docs/guides/storage)
- [Storage Access Control](https://supabase.com/docs/guides/storage/security/access-control)
- [Realtime Guide](https://supabase.com/docs/guides/realtime)
- [Realtime Postgres Changes](https://supabase.com/docs/guides/realtime/postgres-changes)
- [Realtime Broadcast](https://supabase.com/docs/guides/realtime/broadcast)
- [Realtime Presence](https://supabase.com/docs/guides/realtime/presence)

## Next Steps

For common Supabase errors and debugging, see `supabase-common-errors`.
For database queries and CRUD operations, see `supabase-crud-core`.
