React Router v7 Supabase Stack

Convert React Router v7 project instructions (CLAUDE.md files) into working full-stack applications with Supabase authentication, Prisma ORM, and Vercel deployment support.

What This Skill Does

Helps you build and maintain React Router v7 applications using the Supabase + Vercel stack pattern from oreillyjw/supa-vercel-stack. Handles authentication flows, database operations, testing setup, and deployment configuration.

Key Features

Instructions

1. Project Setup & Development

When setting up a new project or starting development:

1. **Initial Setup**:

```bash

npm run setup # Install deps, init Claude, reset DB

npm run dev # Start dev server on localhost:3000

```

2. **Use `.scratchpads/` Directory**:

- Always create planning docs in `.scratchpads/` (gitignored)

- Examples: `.scratchpads/feature-planning.md`, `.scratchpads/migration-notes.md`

- Use for: migration plans, TODOs, research, draft documentation

3. **Essential Commands**:

```bash

npm run build # Build production app

npm run validate # Run all checks: tests, lint, typecheck, e2e

npm test # Vitest unit tests (watch mode)

npm run test:e2e:dev # Playwright interactive testing

npm run typecheck # TypeScript checking

npm run format # Prettier formatting

```

2. Database Management

**Important**: Supabase SQL migrations are the source of truth. Prisma schema is auto-generated.

**Migration Workflow**:

1. **Create Migration**:

```bash

npx supabase migration new feature_name

# Edit generated file in supabase/migrations/

```

2. **Apply Migration**:

```bash

npm run db:reset # Applies migrations, regenerates Prisma, seeds DB

```

3. **Individual Commands**:

```bash

npm run db:reset:supabase # Reset Supabase DB

npm run db:reset:prisma # Pull schema and regenerate client

npm run db:seed # Seed test data

```

**Production Deployment**:

**When to Use Supabase SDK vs Prisma**:

3. Authentication Implementation

**Session Management** ([app/modules/auth/session.server.ts](app/modules/auth/session.server.ts)):

```typescript

// Protect routes (default - no token verification)

const authSession = await requireAuthSession(request);

// Protect critical operations (verify with Supabase)

const authSession = await requireAuthSession(request, { verify: true });

// Refresh on POST/action requests

const { authSession } = await refreshAuthSession(request);

// Must manually commit session after refresh

```

**Key Points**:

**Available Auth Methods**:

4. Module Organization

Structure code in `app/modules/` by domain:

```

app/modules/

├── auth/

│ ├── service.server.ts # Server-side auth logic

│ ├── session.server.ts # Session management

│ ├── types.ts # Type definitions

│ └── components/ # Auth UI components

├── note/

│ ├── service.server.ts # CRUD operations

│ └── types.ts

└── user/

└── service.server.ts

```

Each module exports public API via `index.ts`. Use path alias `~/*` for imports:

```typescript

import { requireAuthSession } from "~/modules/auth";

```

5. Routing Conventions

React Router v7 file-based routing in `app/routes/`:

6. Testing Strategy

**Unit Tests (Vitest)**:

```bash

npm test # Watch mode

npm run test:cov # With coverage

```

**E2E Tests (Playwright)**:

```bash

npm run test:e2e:dev # Interactive UI

npm run test:e2e:run # Headless

```

**Test Seeded Account**:

7. Vercel Deployment

**Prerequisites**:

**Setup**:

1. **Recommended**: Use Supabase Integration from Vercel Marketplace

- Auto-configures all required environment variables

- No manual setup needed

2. **Manual Configuration**:

```

POSTGRES_PRISMA_URL=postgres://postgres:{PASSWORD}@db.{INSTANCE}.supabase.co:5432/postgres

SUPABASE_URL=https://{INSTANCE}.supabase.co

SUPABASE_ANON_KEY={ANON_KEY}

SUPABASE_SERVICE_ROLE_KEY={SERVICE_KEY}

SUPABASE_JWT_SECRET={JWT_SECRET}

```

Find `SUPABASE_JWT_SECRET` in: Supabase Dashboard → Project Settings → API → JWT Settings

3. **Update Supabase URLs**:

- Authentication → URL Configuration

- Add: `https://your-app.vercel.app/oauth/callback`

- Add: `https://your-app.vercel.app/reset-password`

**Deployment Flow**:

8. Security Best Practices

9. Local Development with Supabase

Supabase CLI runs locally on ports 54321-54329:

Configuration: `supabase/config.toml`

10. Styling with Tailwind

Common Workflows

Adding a New Feature Module

1. Create directory: `app/modules/feature-name/`

2. Add `service.server.ts` for business logic

3. Add `types.ts` for TypeScript definitions

4. Create `components/` subdirectory for UI

5. Export public API via `index.ts`

Database Schema Changes

1. Create migration: `npx supabase migration new add_feature`

2. Write SQL in `supabase/migrations/TIMESTAMP_add_feature.sql`

3. Apply: `npm run db:reset`

4. Review auto-generated Prisma schema

5. Update service layer with new queries

Adding Authentication to Route

```typescript

import { requireAuthSession } from "~/modules/auth";

export async function loader({ request }: LoaderFunctionArgs) {

const { userId } = await requireAuthSession(request);

// Your protected route logic

}

```

Important Notes

Environment Variables Reference

Required variables (see `.env.example` for full list):

Resources