CLAUDE.md for supabase/supabase-js

# CLAUDE.md - Supabase JS Libraries Monorepo

## Repository Overview

This unified Nx monorepo consolidates all Supabase JavaScript SDKs. This strategic migration from 6 separate repositories addresses critical maintenance overhead and enables atomic cross-package changes.

## Core Packages

| Package | Purpose |
|---------|---------|
| `supabase-js` | Main client, orchestrates all sub-clients |
| `auth-js` | Authentication (OAuth, email/password, MFA) |
| `realtime-js` | WebSocket connections, presence, broadcast |
| `postgrest-js` | Database queries via PostgREST |
| `storage-js` | File uploads and management |
| `functions-js` | Edge Functions invocation |

## Development Commands

Always use `nx` commands, never direct npm operations:

```bash
# Install dependencies
pnpm install

# Build all packages
pnpm nx run-many -t build

# Build specific package
pnpm nx build @supabase/supabase-js

# Test all packages
pnpm nx run-many -t test

# Test specific package
pnpm nx test @supabase/auth-js

# Lint all
pnpm nx run-many -t lint

# Type check
pnpm nx run-many -t typecheck
```

## Package Dependencies

```
supabase-js
├── auth-js
├── realtime-js
├── postgrest-js
├── storage-js
└── functions-js
```

Changes to sub-packages may require updates to `supabase-js`.

## Testing Requirements

### Running Tests
```bash
# Run specific package tests
pnpm nx test @supabase/auth-js

# Run with coverage
pnpm nx test @supabase/auth-js --coverage

# Run specific test file
pnpm nx test @supabase/auth-js --testFile=session.test.ts
```

### Docker Requirements
Some integration tests require Docker:
```bash
# Start local Supabase
pnpm supabase start

# Stop
pnpm supabase stop
```

## Code Style

### TypeScript Standards
- Strict mode enabled
- Explicit return types on public APIs
- No `any` types
- Use generics for flexible APIs

### Naming Conventions
- PascalCase for types and classes
- camelCase for functions and variables
- SCREAMING_SNAKE_CASE for constants

### Example Pattern
```typescript
export interface PostgrestResponse<T> {
  data: T | null
  error: PostgrestError | null
  count: number | null
  status: number
  statusText: string
}

export async function query<T>(
  url: string,
  options: QueryOptions
): Promise<PostgrestResponse<T>> {
  // Implementation
}
```

## Commit Guidelines

Use conventional commits:
```bash
pnpm run commit
```

Format:
```
feat(auth): add PKCE support for OAuth
fix(realtime): handle reconnection edge case
docs(storage): update upload examples
test(postgrest): add filter combination tests
```

## Release Process

### Versioning Model
- **Canary releases**: Automated on every push to main
- **Stable releases**: Manual trigger with version bump

### Creating a Release
1. Ensure all tests pass
2. Update CHANGELOG.md
3. Run version bump script
4. Create PR for review
5. Merge and tag

## Common Patterns

### Error Handling
```typescript
const { data, error } = await supabase
  .from('users')
  .select('*')

if (error) {
  console.error('Query failed:', error.message)
  return
}

// data is now typed and non-null
```

### Realtime Subscriptions
```typescript
const channel = supabase
  .channel('room1')
  .on('broadcast', { event: 'message' }, (payload) => {
    console.log('Received:', payload)
  })
  .subscribe()

// Cleanup
channel.unsubscribe()
```

### Storage Uploads
```typescript
const { data, error } = await supabase.storage
  .from('avatars')
  .upload('user-123/avatar.png', file, {
    cacheControl: '3600',
    upsert: true
  })
```

## Common Pitfalls

### 1. Direct npm Commands
Always use `pnpm nx` commands instead of direct npm/pnpm commands in packages.

### 2. Missing Type Exports
Ensure all public types are exported from package index.

### 3. Breaking Changes
Any change to public API requires:
- Major version bump consideration
- Migration guide
- Deprecation period for removals

### 4. Test Isolation
Tests must not depend on external services unless explicitly marked as integration tests.

## Project Structure

```
packages/
├── supabase-js/      # Main client
├── auth-js/          # Authentication
├── realtime-js/      # WebSocket client
├── postgrest-js/     # Database client
├── storage-js/       # File storage
└── functions-js/     # Edge functions

tools/
└── scripts/          # Build and release tools

examples/
└── next-js/          # Example applications
```

## Environment Setup

Required environment variables for testing:
```bash
SUPABASE_URL=http://localhost:54321
SUPABASE_ANON_KEY=your-anon-key
SUPABASE_SERVICE_KEY=your-service-key
```

## Getting Help

- Check existing tests for usage examples
- Review package README files
- Run `pnpm nx graph` to visualize dependencies