### Install shadcn/ui with Next.js

Source: https://supabase.com/ui/docs/getting-started/quickstart

Use this command to start a new Next.js project with Supabase UI integration. Ensure you have Node.js and npm/yarn installed.

```bash
npx create-next-app -e with-supabase
```

--------------------------------

### Install All Supabase Skills CLI

Source: https://supabase.com/ui/docs/ai-editors-rules/skills

Installs the full set of Supabase skills for most projects. Run this command in the root of your project.

```bash
npx skills add supabase/agent-skills
```

--------------------------------

### Install Infinite Query Hook

Source: https://supabase.com/ui/docs/infinite-query-hook

Install the infinite query hook using npm, yarn, or pnpm.

```bash
npx shadcn@latest add @supabase/infinite-query-hook
```

--------------------------------

### Install Platform Kit for Next.js

Source: https://supabase.com/ui/docs/platform/platform-kit

Use this command to add the Platform Kit to your Next.js project. Ensure you have npx, npm, yarn, or bun installed.

```bash
npx shadcn@latest add @supabase/platform-kit-nextjs
```

--------------------------------

### Install Supabase Postgres Best Practices Skill CLI

Source: https://supabase.com/ui/docs/ai-editors-rules/skills

Installs the Postgres-specific skill for database work, focusing on performance optimization, query design, and schema best practices. Use this in addition to the full set if you do extensive database work.

```bash
npx skills add supabase/agent-skills --skill supabase-postgres-best-practices
```

--------------------------------

### Install Current User Avatar Next.js

Source: https://supabase.com/ui/docs/nextjs/current-user-avatar

Install the Current User Avatar component for Next.js using npm, yarn, or bun.

```bash
npx shadcn@latest add @supabase/current-user-avatar-nextjs
```

--------------------------------

### Usage Example of CurrentUserAvatar

Source: https://supabase.com/ui/docs/nextjs/current-user-avatar

Demonstrates how to integrate the CurrentUserAvatar component into your Next.js application. This example shows it within a header component.

```typescript
'use client'
 
import { CurrentUserAvatar } from '@/components/current-user-avatar'
 
const CurrentUserAvatarDemo = () => {
  return (
    <Header className="flex items-center justify-between">
      <h1>Lumon Industries</h1>
      <CurrentUserAvatar />
    </Header>
  )
}
 
export default CurrentUserAvatarDemo
```

--------------------------------

### Install Supabase Dropzone for Next.js

Source: https://supabase.com/ui/docs/nextjs/dropzone

Use this command to add the Supabase Dropzone component to your Next.js project.

```bash
npx shadcn@latest add @supabase/dropzone-nextjs
```

--------------------------------

### Basic Realtime Monaco Usage

Source: https://supabase.com/ui/docs/nextjs/realtime-monaco

Demonstrates the basic setup for the Realtime Monaco component, specifying a channel and language.

```typescript
import { RealtimeMonaco } from '@/components/realtime-monaco'
 
export default function MonacoPage() {
  return <RealtimeMonaco channel="realtime-monaco-demo" language="typescript" />
}
```

--------------------------------

### Install Realtime Avatar Stack for Next.js

Source: https://supabase.com/ui/docs/nextjs/realtime-avatar-stack

Use this command to add the Realtime Avatar Stack component to your Next.js project.

```bash
npx shadcn@latest add @supabase/realtime-avatar-stack-nextjs
```

--------------------------------

### Install Supabase Agent Skills as Claude Code Plugin

Source: https://supabase.com/ui/docs/ai-editors-rules/skills

Installs the Supabase agent skills as plugins for Claude Code. This allows Claude Code to discover and use the skills.

```bash
/plugin marketplace add supabase/agent-skills
```

```bash
/plugin install supabase@supabase-agent-skills
```

--------------------------------

### Realtime Monaco with Persistence Enabled

Source: https://supabase.com/ui/docs/nextjs/realtime-monaco

Example of using the Realtime Monaco component with persistence enabled by passing `true` to the `persistence` prop.

```typescript
import { RealtimeMonaco } from '@/components/realtime-monaco'
 
export default function MonacoPage() {
  return <RealtimeMonaco channel="realtime-monaco-demo" language="typescript" persistence />
}
```

--------------------------------

### InfiniteList Demo with Todo List

Source: https://supabase.com/ui/docs/infinite-query-hook

Demonstrates how to use the InfiniteList component with a Todo List data source. It defines a custom `renderItem` function to display individual todo items and a `trailingQuery` to sort the todos by insertion date. Ensure the Checkbox component from shadcn/ui is installed.

```typescript
'use client'

import { InfiniteList } from './infinite-component'
import { Checkbox } from '@/components/ui/checkbox'
import { SupabaseQueryHandler } from '@/hooks/use-infinite-query'
import { Database } from '@/lib/supabase.types'

type TodoTask = Database['public']['Tables']['todos']['Row']

// Define how each item should be rendered
const renderTodoItem = (todo: TodoTask) => {
  return (
    <div
      key={todo.id}
      className="border-b py-3 px-4 hover:bg-muted flex items-center justify-between"
    >
      <div className="flex items-center gap-3">
        <Checkbox defaultChecked={todo.is_complete ?? false} />
        <div>
          <span className="font-medium text-sm text-foreground">{todo.task}</span>
          <div className="text-sm text-muted-foreground">
            {new Date(todo.inserted_at).toLocaleDateString()}
          </div>
        </div>
      </div>
    </div>
  )
}

const orderByInsertedAt: SupabaseQueryHandler<'todos'> = (query) => {
  return query.order('inserted_at', { ascending: false })
}

export const InfiniteListDemo = () => {
  return (
    <div className="bg-background h-[600px]">
      <InfiniteList
        tableName="todos"
        renderItem={renderTodoItem}
        pageSize={3}
        trailingQuery={orderByInsertedAt}
      />
    </div>
  )
}

```

--------------------------------

### Infinite Query Usage with Filtering on Search Params

Source: https://supabase.com/ui/docs/infinite-query-hook

Example of using the `useInfiniteQuery` hook with dynamic filtering based on URL search parameters. It shows how to apply `ilike` filtering to the query.

```typescript
const params = useSearchParams()
const searchQuery = params.get('q')

const { data, isLoading, isFetching, fetchNextPage, count, isSuccess } = useInfiniteQuery({
  tableName: 'products',
  columns: '*',
  pageSize: 10,
  trailingQuery: (query) => {
    if (searchQuery && searchQuery.length > 0) {
      query = query.ilike('name', `%${searchQuery}%`)
    }
    return query
  },
})

return (
  <div>
    {data.map((item) => (
      <ProductCard key={item.id} product={item} />
    ))}
    <Button onClick={fetchNextPage}>Load more products</Button>
  </div>
)
```

--------------------------------

### Infinite Query Usage with Sorting

Source: https://supabase.com/ui/docs/infinite-query-hook

Example of using the `useInfiniteQuery` hook to fetch data with sorting applied. It demonstrates how to use the `trailingQuery` prop for ordering results.

```typescript
const { data, fetchNextPage } = useInfiniteQuery({
  tableName: 'products',
  columns: '*',
  pageSize: 10,
  trailingQuery: (query) => query.order('created_at', { ascending: false }),
})

return (
  <div>
    {data.map((item) => (
      <ProductCard key={item.id} product={item} />
    ))}
    <Button onClick={fetchNextPage}>Load more products</Button>
  </div>
)
```

--------------------------------

### Integrating RealtimeCursors Component in a Next.js Page

Source: https://supabase.com/ui/docs/nextjs/realtime-cursor

This example shows how to integrate the RealtimeCursors component into a Next.js page. Ensure the component is wrapped in 'use client' directive for client-side interactivity. Specify the roomName and username props for room identification and user labeling.

```typescript
'use client'
 
import { RealtimeCursors } from '@/components/realtime-cursors'
 
export default function Page() {
  return (
    <div className="w-full min-h-screen">
      <RealtimeCursors roomName="macrodata_refinement_office" username="Mark Scout" />
    </div>
  )
}
```

--------------------------------

### File Upload Demo Component

Source: https://supabase.com/ui/docs/nextjs/dropzone

Demonstrates how to use the Dropzone component with Supabase upload hooks. Configure bucket name, path, allowed MIME types, and file limits.

```javascript
'use client'
 
import { Dropzone, DropzoneContent, DropzoneEmptyState } from '@/components/dropzone'
import { useSupabaseUpload } from '@/hooks/use-supabase-upload'
 
const FileUploadDemo = () => {
  const props = useSupabaseUpload({
    bucketName: 'test',
    path: 'test',
    allowedMimeTypes: ['image/*'],
    maxFiles: 2,
    maxFileSize: 1000 * 1000 * 10, // 10MB,
  })
 
  return (
    <div className="w-[500px]">
      <Dropzone {...props}>
        <DropzoneEmptyState />
        <DropzoneContent />
      </Dropzone>
    </div>
  )
}
 
export { FileUploadDemo }
```

--------------------------------

### Create Supabase Browser Client

Source: https://supabase.com/ui/docs/react-router/client

Use this function to create a Supabase client for browser environments. Ensure VITE_SUPABASE_URL and VITE_SUPABASE_PUBLISHABLE_KEY are set in your .env.local file.

```typescript
/// <reference types="vite/types/importMeta.d.ts" />
import { createBrowserClient } from '@supabase/ssr'

export function createClient() {
  return createBrowserClient(
    import.meta.env.VITE_SUPABASE_URL!,
    import.meta.env.VITE_SUPABASE_PUBLISHABLE_KEY!
  )
}
```

--------------------------------

### Realtime Chat with Message Persistence - JSX

Source: https://supabase.com/ui/docs/nextjs/realtime-chat

Illustrates how to handle new messages for persistence by using the `onMessage` callback. This allows storing messages in a database.

```jsx
import { RealtimeChat } from '@/components/realtime-chat'
import { useMessagesQuery } from '@/hooks/use-messages-query'
import { storeMessages } from '@/lib/store-messages'
 
export default function ChatPage() {
  const { data: messages } = useMessagesQuery()
  const handleMessage = async (messages: ChatMessage[]) => {
    // Store messages in your database
    await storeMessages(messages)
  }
 
  return <RealtimeChat roomName="my-chat-room" username="john_doe" onMessage={handleMessage} />
}
```

--------------------------------

### Realtime Chat with Initial Messages - JSX

Source: https://supabase.com/ui/docs/nextjs/realtime-chat

Shows how to initialize the RealtimeChat component with a list of existing messages. This is useful for displaying chat history upon loading.

```jsx
import { RealtimeChat } from '@/components/realtime-chat'
import { useMessagesQuery } from '@/hooks/use-messages-query'
 
export default function ChatPage() {
  const { data: messages } = useMessagesQuery()
 
  return <RealtimeChat roomName="my-chat-room" username="john_doe" messages={messages} />
}
```

--------------------------------

### DropzoneEmptyState Component

Source: https://supabase.com/ui/docs/nextjs/dropzone

Displays the initial empty state of the dropzone, prompting users to upload files. Shows upload instructions, maximum file count, and maximum file size if configured.

```javascript
const DropzoneEmptyState = ({ className }: { className?: string }) => {
  const { maxFiles, maxFileSize, inputRef, isSuccess } = useDropzoneContext()

  if (isSuccess) {
    return null
  }

  return (
    <div className={cn('flex flex-col items-center gap-y-2', className)}>
      <Upload size={20} className="text-muted-foreground" />
      <p className="text-sm">
        Upload{!!maxFiles && maxFiles > 1 ? ` ${maxFiles}` : ''} file
        {!maxFiles || maxFiles > 1 ? 's' : ''}
      </p>
      <div className="flex flex-col items-center gap-y-1">
        <p className="text-xs text-muted-foreground">
          Drag and drop or{' '}
          <a
            onClick={() => inputRef.current?.click()}
            className="underline cursor-pointer transition hover:text-foreground"
          >
            select {maxFiles === 1 ? `file` : 'files'}
          </a>{' '}
          to upload
        </p>
        {maxFileSize !== Number.POSITIVE_INFINITY && (
          <p className="text-xs text-muted-foreground">
            Maximum file size: {formatBytes(maxFileSize, 2)}
          </p>
        )}
      </div>
    </div>
  )
}
```

--------------------------------

### Environment Variables for Supabase Management

Source: https://supabase.com/ui/docs/platform/platform-kit

Configure your environment variables in a `.env.local` file to enable Supabase management features, including AI queries. Ensure your personal access token and API keys are securely managed.

```dotenv
SUPABASE_MANAGEMENT_API_TOKEN=your-personal-access-token
NEXT_PUBLIC_ENABLE_AI_QUERIES=true
OPENAI_API_KEY=your-openai-api-key
```

--------------------------------

### useInfiniteQuery Hook Implementation

Source: https://supabase.com/ui/docs/infinite-query-hook

This hook fetches data from a Supabase table in pages, handling loading states, errors, and providing a way to fetch the next page. It uses a store-like pattern to manage state.

```typescript
'use client'

import { PostgrestQueryBuilder, type PostgrestClientOptions } from '@supabase/postgrest-js'
import { type SupabaseClient } from '@supabase/supabase-js'
import { useEffect, useRef, useSyncExternalStore } from 'react'

import { createClient } from '@/lib/supabase/client'

const supabase = createClient()

// The following types are used to make the hook type-safe. It extracts the database type from the supabase client.
type SupabaseClientType = typeof supabase

// Utility type to check if the type is any
type IfAny<T, Y, N> = 0 extends 1 & T ? Y : N

// Extracts the database type from the supabase client. If the supabase client doesn't have a type, it will fallback properly.
type Database =
  SupabaseClientType extends SupabaseClient<infer U>
    ? IfAny<
        U,
        {
          public: { 
            Tables: Record<string, any>
            Views: Record<string, any>
            Functions: Record<string, any>
          }
        },
        U
      >
    : {
        public: {
          Tables: Record<string, any>
          Views: Record<string, any>
          Functions: Record<string, any>
        }
      }

// Change this to the database schema you want to use
type DatabaseSchema = Database['public']

// Extracts the table names from the database type
type SupabaseTableName = keyof DatabaseSchema['Tables']

// Extracts the table definition from the database type
type SupabaseTableData<T extends SupabaseTableName> = DatabaseSchema['Tables'][T]['Row']

// Default client options for PostgrestQueryBuilder
type DefaultClientOptions = PostgrestClientOptions

type SupabaseSelectBuilder<T extends SupabaseTableName> = ReturnType<
  PostgrestQueryBuilder<
    DefaultClientOptions,
    DatabaseSchema,
    DatabaseSchema['Tables'][T],
    T
  >['select']
>

// A function that modifies the query. Can be used to sort, filter, etc. If .range is used, it will be overwritten.
type SupabaseQueryHandler<T extends SupabaseTableName> = (
  query: SupabaseSelectBuilder<T>
) => SupabaseSelectBuilder<T>

interface UseInfiniteQueryProps<T extends SupabaseTableName, Query extends string = '*'> {
  // The table name to query
  tableName: T
  // The columns to select, defaults to `*`
  columns?: string
  // The number of items to fetch per page, defaults to `20`
  pageSize?: number
  // A function that modifies the query. Can be used to sort, filter, etc. If .range is used, it will be overwritten.
  trailingQuery?: SupabaseQueryHandler<T>
}

interface StoreState<TData> {
  data: TData[]
  count: number
  isSuccess: boolean
  isLoading: boolean
  isFetching: boolean
  error: Error | null
  hasInitialFetch: boolean
}

type Listener = () => void

function createStore<TData extends SupabaseTableData<T>, T extends SupabaseTableName>(
  props: UseInfiniteQueryProps<T>
) {
  const { tableName, columns = '*', pageSize = 20, trailingQuery } = props

  let state: StoreState<TData> = {
    data: [],
    count: 0,
    isSuccess: false,
    isLoading: false,
    isFetching: false,
    error: null,
    hasInitialFetch: false,
  }

  const listeners = new Set<Listener>()

  const notify = () => {
    listeners.forEach((listener) => listener())
  }

  const setState = (newState: Partial<StoreState<TData>>) => {
    state = { ...state, ...newState }
    notify()
  }

  const fetchPage = async (skip: number) => {
    if (state.hasInitialFetch && (state.isFetching || state.count <= state.data.length)) return

    setState({ isFetching: true })

    let query = supabase
      .from(tableName)
      .select(columns, { count: 'exact' }) as unknown as SupabaseSelectBuilder<T>

    if (trailingQuery) {
      query = trailingQuery(query)
    }
    const { data: newData, count, error } = await query.range(skip, skip + pageSize - 1)

    if (error) {
      console.error('An unexpected error occurred:', error)
      setState({ error })
    } else {
      setState({
        data: [...state.data, ...(newData as TData[])],
        count: count || 0,
        isSuccess: true,
        error: null,
      })
    }
    setState({ isFetching: false })
  }

  const fetchNextPage = async () => {
    if (state.isFetching) return
    await fetchPage(state.data.length)
  }

  const initialize = async () => {
    setState({ isLoading: true, isSuccess: false, data: [] })
    await fetchNextPage()
    setState({ isLoading: false, hasInitialFetch: true })
  }

  return {
    getState: () => state,
    subscribe: (listener: Listener) => {
      listeners.add(listener)
      return () => listeners.delete(listener)
    },
    fetchNextPage,

```

--------------------------------

### AI SQL Generation API Route

Source: https://supabase.com/ui/docs/platform/platform-kit

This API route handles POST requests to generate SQL queries. It requires a 'prompt' and 'projectRef' in the request body. It first retrieves the database schema, formats it, and then uses OpenAI to generate the SQL query. Error handling is included for missing parameters, permission issues, and AI generation failures.

```typescript
1import {
  NextResponse
} from 'next/server'
import OpenAI from 'openai'
import createClient from 'openapi-fetch'

import type { paths } from '@/platform/platform-kit-nextjs/lib/management-api-schema'
import { listTablesSql } from '@/platform/platform-kit-nextjs/lib/pg-meta'

const openai = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
})

const client = createClient<paths>({
  baseUrl: 'https://api.supabase.com',
  headers: {
    Authorization: `Bearer ${process.env.SUPABASE_MANAGEMENT_API_TOKEN}`,
  },
})

// Function to get database schema
async function getDbSchema(projectRef: string) {
  const token = process.env.SUPABASE_MANAGEMENT_API_TOKEN
  if (!token) {
    throw new Error('Supabase Management API token is not configured.')
  }

  const sql = listTablesSql()

  const { data, error } = await client.POST('/v1/projects/{ref}/database/query', {
    params: {
      path: {
        ref: projectRef,
      },
    },
    body: {
      query: sql,
      read_only: true,
    },
  })

  if (error) {
    throw error
  }

  return data as any
}

function formatSchemaForPrompt(schema: any) {
  let schemaString = ''
  if (schema && Array.isArray(schema)) {
    schema.forEach((table: any) => {
      const columnInfo = table.columns.map((c: any) => `${c.name} (${c.data_type})`)
      schemaString += `Table "${table.name}" has columns: ${columnInfo.join(', ')}.\n`
    })
  }
  return schemaString
}

export async function POST(request: Request) {
  try {
    const { prompt, projectRef } = await request.json()

    if (!prompt) {
      return NextResponse.json({ message: 'Prompt is required.' }, { status: 400 })
    }
    if (!projectRef) {
      return NextResponse.json({ message: 'projectRef is required.' }, { status: 400 })
    }

    // Implement your permission check here (e.g. check if the user is a member of the project)
    // In this example, everyone can access all projects
    const userHasPermissionForProject = Boolean(projectRef)

    if (!userHasPermissionForProject) {
      return NextResponse.json(
        { message: 'You do not have permission to access this project.' },
        { status: 403 }
      )
    }

    // 1. Get database schema
    const schema = await getDbSchema(projectRef)
    const formattedSchema = formatSchemaForPrompt(schema)

    // 2. Create a prompt for OpenAI
    const systemPrompt = `You are an expert SQL assistant. Given the following database schema, write a SQL query that answers the user's question. Return only the SQL query, do not include any explanations or markdown.\n\nSchema:\n${formattedSchema}`

    // 3. Call OpenAI to generate SQL using responses.create (plain text output)
    const response = await openai.responses.create({
      model: 'gpt-4.1',
      instructions: systemPrompt, // Use systemPrompt as instructions
      input: prompt, // User's question
    })

    const sql = response.output_text

    if (!sql) {
      return NextResponse.json(
        { message: 'Could not generate SQL from the prompt.' },
        { status: 500 }
      )
    }

    // 4. Return the generated SQL
    return NextResponse.json({ sql })
  } catch (error: any) {
    console.error('AI SQL generation error:', error)
    const errorMessage = error.message || 'An unexpected error occurred.'
    const status = error.response?.status || 500
    return NextResponse.json({ message: errorMessage }, { status })
  }
}
```

--------------------------------

### Realtime Monaco with Custom Persistence Options

Source: https://supabase.com/ui/docs/nextjs/realtime-monaco

Configures the Realtime Monaco component with specific persistence options, including table and column names, and a store timeout.

```jsx
<RealtimeMonaco
  channel="realtime-monaco-demo"
  language="typescript"
  persistence={{
    table: 'yjs_documents',
    roomColumn: 'room',
    stateColumn: 'state',
    storeTimeout: 2000,
  }}
/>
```

--------------------------------

### SupabasePersistenceOptions Configuration

Source: https://supabase.com/ui/docs/nextjs/realtime-monaco

Details the available options for configuring Supabase persistence for Yjs documents.

```APIDOC
## SupabasePersistenceOptions

This object allows you to configure how Yjs documents are persisted to a Supabase database.

### Options

| Option        | Type    | Default       | Description                                       |
|---------------|---------|---------------|---------------------------------------------------|
| `table`       | `string`| `'yjs_documents'`| Name of the Postgres table used to store documents. |
| `schema`      | `string`| `'public'`    | Schema where the table is located.                |
| `roomColumn`  | `string`| `'room'`      | Column used as the document identifier.           |
| `stateColumn` | `string`| `'state'`     | Column used to store the binary Yjs state.        |
| `storeTimeout`| `number`| `1000`        | Debounce delay (ms) before persisting changes.    |
```

--------------------------------

### Infinite Query Hook Implementation

Source: https://supabase.com/ui/docs/infinite-query-hook

The core implementation of the `useInfiniteQuery` hook. It manages data fetching, state synchronization, and initialization for progressive data loading from Supabase.

```typescript
const initialState: any = {
  data: [],
  count: 0,
  isSuccess: false,
  isLoading: false,
  isFetching: false,
  error: null,
  hasInitialFetch: false,
}

function useInfiniteQuery<TData extends SupabaseTableData<T>, T extends SupabaseTableName = SupabaseTableName>(
  props: UseInfiniteQueryProps<T>
) {
  const storeRef = useRef(createStore<TData, T>(props))

  const state = useSyncExternalStore(
    storeRef.current.subscribe,
    () => storeRef.current.getState(),
    () => initialState as StoreState<TData>
  )

  useEffect(() => {
    // Recreate store if props change
    if (
      storeRef.current.getState().hasInitialFetch &&
      (
        props.tableName !== props.tableName ||
        props.columns !== props.columns ||
        props.pageSize !== props.pageSize
      )
    ) {
      storeRef.current = createStore<TData, T>(props)
    }

    if (!state.hasInitialFetch && typeof window !== 'undefined') {
      storeRef.current.initialize()
    }
  }, [props.tableName, props.columns, props.pageSize, state.hasInitialFetch])

  return {
    data: state.data,
    count: state.count,
    isSuccess: state.isSuccess,
    isLoading: state.isLoading,
    isFetching: state.isFetching,
    error: state.error,
    hasMore: state.count > state.data.length,
    fetchNextPage: storeRef.current.fetchNextPage,
  }
}

export {
  useInfiniteQuery,
  type SupabaseQueryHandler,
  type SupabaseTableData,
  type SupabaseTableName,
  type UseInfiniteQueryProps,
}
```

--------------------------------

### Basic Realtime Chat Usage - JSX

Source: https://supabase.com/ui/docs/nextjs/realtime-chat

Demonstrates the basic integration of the RealtimeChat component into a Next.js application. Requires specifying a room name and username.

```jsx
import { RealtimeChat } from '@/components/realtime-chat'
 
export default function ChatPage() {
  return <RealtimeChat roomName="my-chat-room" username="john_doe" />
}
```

--------------------------------

### Sign-up Email Template HTML

Source: https://supabase.com/ui/docs/nextjs/password-based-auth

HTML structure for the sign-up confirmation email template in Supabase. Includes placeholders for site URL, token hash, and redirect URL.

```html
<h2>Confirm your signup</h2>
 
<p>Follow this link to confirm your user:</p>
<p>
  <a
    href="{{ .SiteURL }}/auth/confirm?token_hash={{ .TokenHash }}&type=email&next={{ .RedirectTo }}"
    >Confirm your email</a
  >
</p>
```

--------------------------------

### Create Table for Persistence

Source: https://supabase.com/ui/docs/nextjs/realtime-monaco

SQL statement to create the necessary table in Supabase for persisting Yjs document state.

```sql
create table yjs_documents (
  room text primary key,
  state text not null
);
```

--------------------------------

### Create Supabase Browser Client for Next.js

Source: https://supabase.com/ui/docs/nextjs/client

Use this function to create a Supabase client for browser-side operations in your Next.js application. Ensure NEXT_PUBLIC_SUPABASE_URL and NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY environment variables are set.

```typescript
import { createBrowserClient } from '@supabase/ssr'

export function createClient() {
  return createBrowserClient(
    process.env.NEXT_PUBLIC_SUPABASE_URL!,
    process.env.NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY!
  )
}
```

--------------------------------

### Usage of RealtimeAvatarStack Component

Source: https://supabase.com/ui/docs/nextjs/realtime-avatar-stack

Integrate the RealtimeAvatarStack component into your Next.js application to display online users. Pass a `roomName` prop to specify the Supabase Realtime room.

```typescript
import { RealtimeAvatarStack } from '@/components/realtime-avatar-stack'
 
export default function Page() {
  return (
    <Header className="flex items-center justify-between">
      <h1>Lumon Industries</h1>
      <RealtimeAvatarStack roomName="break_room" />
    </Header>
  )
}
```

--------------------------------

### Supabase UI File Upload Component Props

Source: https://supabase.com/ui/docs/nextjs/dropzone

Configuration options for the Supabase UI file upload component.

```APIDOC
## Props

### `bucketName`
*   **Type**: `string`
*   **Default**: `null`
*   **Description**: The name of the Supabase Storage bucket to upload to.

### `path`
*   **Type**: `string`
*   **Default**: `null`
*   **Description**: The path or subfolder to upload the file to.

### `allowedMimeTypes`
*   **Type**: `string[]`
*   **Default**: `[]`
*   **Description**: The MIME types to allow for upload.

### `maxFiles`
*   **Type**: `number`
*   **Default**: `1`
*   **Description**: Maximum number of files to upload.

### `maxFileSize`
*   **Type**: `number`
*   **Default**: `1000`
*   **Description**: Maximum file size in bytes.
```

--------------------------------

### InfiniteList Component Implementation

Source: https://supabase.com/ui/docs/infinite-query-hook

This component abstracts the useInfiniteQuery hook into a reusable UI element for infinite scrolling lists. It includes utility components for no results, end of list messages, and skeleton loaders. It uses an Intersection Observer to trigger fetching more data when the user scrolls near the bottom.

```typescript
'use client'

import * as React from 'react'

import {
  SupabaseQueryHandler,
  SupabaseTableData,
  SupabaseTableName,
  useInfiniteQuery,
} from '@/hooks/use-infinite-query'
import { cn } from '@/lib/utils'

interface InfiniteListProps<TableName extends SupabaseTableName> {
  tableName: TableName
  columns?: string
  pageSize?: number
  trailingQuery?: SupabaseQueryHandler<TableName>
  renderItem: (item: SupabaseTableData<TableName>, index: number) => React.ReactNode
  className?: string
  renderNoResults?: () => React.ReactNode
  renderEndMessage?: () => React.ReactNode
  renderSkeleton?: (count: number) => React.ReactNode
}

const DefaultNoResults = () => (
  <div className="text-center text-muted-foreground py-10">No results.</div>
)

const DefaultEndMessage = () => (
  <div className="text-center text-muted-foreground py-4 text-sm">You&apos;ve reached the end.</div>
)

const defaultSkeleton = (count: number) => (
  <div className="flex flex-col gap-2 px-4">
    {Array.from({ length: count }).map((_, index) => (
      <div key={index} className="h-4 w-full bg-muted animate-pulse" />
    ))}
  </div>
)

export function InfiniteList<TableName extends SupabaseTableName>({
  tableName,
  columns = '*',
  pageSize = 20,
  trailingQuery,
  renderItem,
  className,
  renderNoResults = DefaultNoResults,
  renderEndMessage = DefaultEndMessage,
  renderSkeleton = defaultSkeleton,
}: InfiniteListProps<TableName>) {
  const { data, isFetching, hasMore, fetchNextPage, isSuccess } = useInfiniteQuery({
    tableName,
    columns,
    pageSize,
    trailingQuery,
  })

  // Ref for the scrolling container
  const scrollContainerRef = React.useRef<HTMLDivElement>(null)

  // Intersection observer logic - target the last rendered *item* or a dedicated sentinel
  const loadMoreSentinelRef = React.useRef<HTMLDivElement>(null)
  const observer = React.useRef<IntersectionObserver | null>(null)

  React.useEffect(() => {
    if (observer.current) observer.current.disconnect()

    observer.current = new IntersectionObserver(
      (entries) => {
        if (entries[0].isIntersecting && hasMore && !isFetching) {
          fetchNextPage()
        }
      },
      {
        root: scrollContainerRef.current, // Use the scroll container for scroll detection
        threshold: 0.1, // Trigger when 10% of the target is visible
        rootMargin: '0px 0px 100px 0px', // Trigger loading a bit before reaching the end
      }
    )

    if (loadMoreSentinelRef.current) {
      observer.current.observe(loadMoreSentinelRef.current)
    }

    return () => {
      if (observer.current) observer.current.disconnect()
    }
  }, [isFetching, hasMore, fetchNextPage])

  return (
    <div ref={scrollContainerRef} className={cn('relative h-full overflow-auto', className)}>
      <div>
        {isSuccess && data.length === 0 && renderNoResults()}

        {data.map((item, index) => renderItem(item, index))}

        {isFetching && renderSkeleton && renderSkeleton(pageSize)}

        <div ref={loadMoreSentinelRef} style={{ height: '1px' }} />

        {!hasMore && data.length > 0 && renderEndMessage()}
      </div>
    </div>
  )
}

```

--------------------------------

### Verify Email OTP in Next.js Route Handler

Source: https://supabase.com/ui/docs/nextjs/password-based-auth

This route handler verifies the email OTP token and redirects the user. Ensure the `createClient` function is correctly set up in your project.

```typescript
import { type EmailOtpType } from '@supabase/supabase-js'
import { redirect } from 'next/navigation'
import { type NextRequest } from 'next/server'

import { createClient } from '@/lib/supabase/server'

export async function GET(request: NextRequest) {
  const { searchParams } = new URL(request.url)
  const token_hash = searchParams.get('token_hash')
  const type = searchParams.get('type') as EmailOtpType | null
  const _next = searchParams.get('next')
  const next = _next?.startsWith('/') ? _next : '/'

  if (token_hash && type) {
    const supabase = await createClient()

    const { error } = await supabase.auth.verifyOtp({
      type,
      token_hash,
    })
    if (!error) {
      // redirect user to specified redirect URL or root of app
      redirect(next)
    } else {
      // redirect the user to an error page with some instructions
      redirect(`/auth/error?error=${error?.message}`)
    }
  }

  // redirect the user to an error page with some instructions
  redirect(`/auth/error?error=No token hash or type`)
}
```

--------------------------------

### Dropzone Component Implementation

Source: https://supabase.com/ui/docs/nextjs/dropzone

A React component for file uploads, integrating with Supabase. It handles drag-and-drop, file validation, and displays upload status.

```typescript
1'use client'
2
3import { CheckCircle, File, Loader2, Upload, X } from 'lucide-react'
4import { createContext, useCallback, useContext, type PropsWithChildren } from 'react'
5
6import { cn } from '@/lib/utils'
7import { type UseSupabaseUploadReturn } from '@/hooks/use-supabase-upload'
8import { Button } from '@/components/ui/button'
9
10export const formatBytes = (
11  bytes: number,
12  decimals = 2,
13  size?: 'bytes' | 'KB' | 'MB' | 'GB' | 'TB' | 'PB' | 'EB' | 'ZB' | 'YB'
14) => {
15  const k = 1000
16  const dm = decimals < 0 ? 0 : decimals
17  const sizes = ['bytes', 'KB', 'MB', 'GB', 'TB', 'PB', 'EB', 'ZB', 'YB']
18
19  if (bytes === 0 || bytes === undefined) return size !== undefined ? `0 ${size}` : '0 bytes'
20  const i = size !== undefined ? sizes.indexOf(size) : Math.floor(Math.log(bytes) / Math.log(k))
21  return parseFloat((bytes / Math.pow(k, i)).toFixed(dm)) + ' ' + sizes[i]
22}
23
24type DropzoneContextType = Omit<UseSupabaseUploadReturn, 'getRootProps' | 'getInputProps'>
25
26const DropzoneContext = createContext<DropzoneContextType | undefined>(undefined)
27
28type DropzoneProps = UseSupabaseUploadReturn & {
29  className?: string
30}
31
32const Dropzone = ({
33  className,
34  children,
35  getRootProps,
36  getInputProps,
37  ...restProps
38}: PropsWithChildren<DropzoneProps>) => {
39  const isSuccess = restProps.isSuccess
40  const isActive = restProps.isDragActive
41  const isInvalid =
42    (restProps.isDragActive && restProps.isDragReject) ||
43    (restProps.errors.length > 0 && !restProps.isSuccess) ||
44    restProps.files.some((file) => file.errors.length !== 0)
45
46  return (
47    <DropzoneContext.Provider value={{ ...restProps }}>
48      <div
49        {...getRootProps({
50          className: cn(
51            'border-2 border-gray-300 rounded-lg p-6 text-center bg-card transition-colors duration-300 text-foreground',
52            className,
53            isSuccess ? 'border-solid' : 'border-dashed',
54            isActive && 'border-primary bg-primary/10',
55            isInvalid && 'border-destructive bg-destructive/10'
56          ),
57        })}
58      >
59        <input {...getInputProps()} />
60        {children}
61      </div>
62    </DropzoneContext.Provider>
63  )
64}
65const DropzoneContent = ({ className }: { className?: string }) => {
66  const {
67    files,
68    setFiles,
69    onUpload,
70    loading,
71    successes,
72    errors,
73    maxFileSize,
74    maxFiles,
75    isSuccess,
76  } = useDropzoneContext()
77
78  const exceedMaxFiles = files.length > maxFiles
79
80  const handleRemoveFile = useCallback(
81    (fileName: string) => {
82      setFiles(files.filter((file) => file.name !== fileName))
83    },
84    [files, setFiles]
85  )
86
87  if (isSuccess) {
88    return (
89      <div className={cn('flex flex-row items-center gap-x-2 justify-center', className)}>
90        <CheckCircle size={16} className="text-primary" />
91        <p className="text-primary text-sm">
92          Successfully uploaded {files.length} file{files.length > 1 ? 's' : ''}
93        </p>
94      </div>
95    )
96  }
97
98  return (
99    <div className={cn('flex flex-col', className)}>
100      {files.map((file, idx) => {
101        const fileError = errors.find((e) => e.name === file.name)
102        const isSuccessfullyUploaded = !!successes.find((e) => e === file.name)
103
104        return (
105          <div
106            key={`${file.name}-${idx}`}
107            className="flex items-center gap-x-4 border-b py-2 first:mt-4 last:mb-4 "
108          >
109            {file.type.startsWith('image/') ? (
110              <div className="h-10 w-10 rounded border overflow-hidden shrink-0 bg-muted flex items-center justify-center">
111                <img src={file.preview} alt={file.name} className="object-cover" />
112              </div>
113            ) : (
114              <div className="h-10 w-10 rounded border bg-muted flex items-center justify-center">
115                <File size={18} />
116              </div>
117            )}
118
119            <div className="shrink grow flex flex-col items-start truncate">
120              <p title={file.name} className="text-sm truncate max-w-full">
121                {file.name}
122              </p>
123              {file.errors.length > 0 ? (
124                <p className="text-xs text-destructive">
125                  {file.errors
126                    .map((e) =>
127                      e.message.startsWith('File is larger than')
128                        ? `File is larger than ${formatBytes(maxFileSize, 2)} (Size: ${formatBytes(file.size, 2)})`
129                        : e.message
130                    )
131                    .join(', ')}
132                </p>
133              ) : loading && !isSuccessfullyUploaded ? (

```

--------------------------------

### RealtimeMonaco Component Implementation

Source: https://supabase.com/ui/docs/nextjs/realtime-monaco

The core React component for the Realtime Monaco editor. It uses the `useConnectOnMount` hook to establish connections for persistence and awareness.

```typescript
'use client'

import { Editor } from '@monaco-editor/react'
import { SupabasePersistenceOptions } from '@supabase-labs/y-supabase'
import { Awareness } from 'y-protocols/awareness.js'

import { useConnectOnMount } from '../hooks/use-connect-on-mount'

type RealtimeMonacoProps = {
  channel: string
  language?: string
  height?: string | number
  className?: string
  awareness?: boolean | Awareness
  persistence?: boolean | SupabasePersistenceOptions
  theme?: 'light' | 'dark'
}

const DEFAULT_HEIGHT = 550

const RealtimeMonaco = ({
  channel,
  language = 'javascript',
  height = DEFAULT_HEIGHT,
  awareness = true,
  persistence,
  theme,
  ...rest
}: RealtimeMonacoProps) => {
  const { connectOnMount } = useConnectOnMount({ channel, persistence, awareness })

  return (
    <Editor
      height={height}
      language={language}
      theme={theme === 'dark' ? 'vs-dark' : 'light'}
      onMount={connectOnMount}
      {...rest}
    />
  )
}

export { RealtimeMonaco }
```

--------------------------------

### Add Toaster for Notifications in Root Layout

Source: https://supabase.com/ui/docs/platform/platform-kit

Include the Toaster component in your application's root layout file (e.g., `layout.tsx` or `App.tsx`) to display toast notifications for Supabase-related events.

```javascript
import { Toaster } from '@/components/ui/sonner'

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <head />
      <body>
        <main>{children}</main>
        <Toaster />
      </body>
    </html>
  )
}
```

--------------------------------

### Format Bytes Utility Function

Source: https://supabase.com/ui/docs/nextjs/dropzone

Converts bytes into a human-readable format (KB, MB, GB, etc.). Useful for displaying file sizes.

```typescript
export const formatBytes = (
  bytes: number,
  decimals = 2,
  size?: 'bytes' | 'KB' | 'MB' | 'GB' | 'TB' | 'PB' | 'EB' | 'ZB' | 'YB'
) => {
  const k = 1000
  const dm = decimals < 0 ? 0 : decimals
  const sizes = ['bytes', 'KB', 'MB', 'GB', 'TB', 'PB', 'EB', 'ZB', 'YB']

  if (bytes === 0 || bytes === undefined) return size !== undefined ? `0 ${size}` : '0 bytes'
  const i = size !== undefined ? sizes.indexOf(size) : Math.floor(Math.log(bytes) / Math.log(k))
  return parseFloat((bytes / Math.pow(k, i)).toFixed(dm)) + ' ' + sizes[i]
}
```

--------------------------------

### Embed Supabase Manager Dialog in React App

Source: https://supabase.com/ui/docs/platform/platform-kit

Use this snippet to embed the Supabase Manager dialog in your React application. Ensure you replace 'your-project-ref' with your actual Supabase project reference.

```javascript
import { useState } from 'react' 

import SupabaseManagerDialog from '@/components/supabase-manager'
import { Button } from '@/components/ui/button'
import { useMobile } from '@/hooks/use-mobile'

export default function Example() {
  const [open, setOpen] = useState(false)
  const projectRef = 'your-project-ref' // Replace with your actual project ref
  const isMobile = useMobile()

  return (
    <>
      <Button onClick={() => setOpen(true)}>Open Supabase Manager</Button>
      <SupabaseManagerDialog
        projectRef={projectRef}
        open={open}
        onOpenChange={setOpen}
        isMobile={isMobile}
      />
    </>
  )
}
```

--------------------------------

### useDropzoneContext Hook

Source: https://supabase.com/ui/docs/nextjs/dropzone

Custom hook to access the Dropzone context. Throws an error if used outside of a Dropzone component, ensuring proper component hierarchy.

```javascript
const useDropzoneContext = () => {
  const context = useContext(DropzoneContext)

  if (!context) {
    throw new Error('useDropzoneContext must be used within a Dropzone')
  }

  return context
}
```

--------------------------------

### CurrentUserAvatar Component

Source: https://supabase.com/ui/docs/nextjs/current-user-avatar

This component fetches and displays the current user's avatar from Supabase Auth. It falls back to showing initials if no image is found. Ensure you have the necessary hooks and UI components imported.

```typescript
'use client'

import { useCurrentUserImage } from '@/hooks/use-current-user-image'
import { useCurrentUserName } from '@/hooks/use-current-user-name'
import { Avatar, AvatarFallback, AvatarImage } from '@/components/ui/avatar'

export const CurrentUserAvatar = () => {
  const profileImage = useCurrentUserImage()
  const name = useCurrentUserName()
  const initials = name
    ?.split(' ')
    ?.map((word) => word[0])
    ?.join('')
    ?.toUpperCase()

  return (
    <Avatar>
      {profileImage && <AvatarImage src={profileImage} alt={initials} />}
      <AvatarFallback>{initials}</AvatarFallback>
    </Avatar>
  )
}
```

--------------------------------

### Cursor Component for Realtime Cursor Sharing

Source: https://supabase.com/ui/docs/nextjs/realtime-cursor

This React component displays a user's cursor and name, styled with a specified color. It's designed to be used within a real-time collaboration context.

```typescript
import { MousePointer2 } from 'lucide-react'

import { cn } from '@/lib/utils'

export const Cursor = ({
  className,
  style,
  color,
  name,
}: {
  className?: string
  style?: React.CSSProperties
  color: string
  name: string
}) => {
  return (
    <div className={cn('pointer-events-none', className)} style={style}>
      <MousePointer2 color={color} fill={color} size={30} />

      <div
        className="mt-1 px-2 py-1 rounded text-xs font-bold text-white text-center"
        style={{ backgroundColor: color }}
      >
        {name}
      </div>
    </div>
  )
}
```