║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║

Supabase Registry Structure Analysis

Key Findings from Supabase UI Library

After deep analysis of /supabase/apps/ui-library, here are the critical patterns we need to adopt:

---

1. Registry Organization Pattern

Current Elements Structure (Wrong)

registry/
└── default/
    └── blocks/
        ├── clerk/          # ❌ Provider subdirectories
        │   ├── clerk-sign-in-shadcn/
        │   └── clerk-sign-up-shadcn/
        ├── tinte/
        └── polar/

Supabase Structure (Correct)

registry/
├── index.ts                 # Main export, imports from organizer files
├── blocks.ts                # Organizes all blocks
├── clients.ts               # Framework-specific clients
├── examples.ts              # Demo components for documentation
├── platform.ts              # Platform-specific components
├── utils.ts                 # Registry utilities (registryItemAppend)
└── default/
    ├── blocks/              # ✅ FLAT structure, no provider subdirs
    │   ├── dropzone/
    │   ├── realtime-cursor/
    │   ├── current-user-avatar/
    │   └── password-based-auth-nextjs/
    ├── clients/
    │   ├── nextjs/
    │   ├── react/
    │   ├── react-router/
    │   └── tanstack/
    ├── examples/            # Demo/preview components
    │   ├── dropzone-demo.tsx
    │   └── realtime-cursor-demo.tsx
    └── fixtures/            # Shared types, database schemas

Key Insight: Components are FLAT, not nested by provider. Provider info is in the name.

---

2. The Organizer File Pattern

registry/blocks.ts

import { type RegistryItem } from 'shadcn/schema'
import { clients } from './clients'
import { registryItemAppend } from './utils'

// Import registry-item.json files
import dropzone from './default/blocks/dropzone/registry-item.json' with { type: 'json' }
import realtimeCursor from './default/blocks/realtime-cursor/registry-item.json' with { type: 'json' }

// Helper to combine component with all clients
const combine = (component: RegistryItem) => {
  return clients.flatMap((client) => {
    return registryItemAppend(
      {
        ...component,
        name: `${component.name}-${client.name.replace('supabase-client-', '')}`,
      },
      [client]
    )
  })
}

// Specific client selection
const nextjsClient = clients.find((client) => client.name === 'supabase-client-nextjs')

export const blocks = [
  // Auto-combine with all clients
  ...combine(dropzone as RegistryItem),
  ...combine(realtimeCursor as RegistryItem),

  // Manual framework-specific combination
  registryItemAppend(passwordBasedAuthNextjs as RegistryItem, [nextjsClient!]),
] as RegistryItem[]

registry/clients.ts

import type { RegistryItem } from 'shadcn/schema'
import nextjs from './default/clients/nextjs/registry-item.json' with { type: 'json' }
import react from './default/clients/react/registry-item.json' with { type: 'json' }

export const clients = [nextjs, react] as RegistryItem[]

registry/examples.ts

import type { RegistryItem } from 'shadcn/schema'

export const examples: RegistryItem[] = [
  {
    name: 'dropzone-demo',
    type: 'registry:example',
    registryDependencies: [],
    files: [
      {
        path: 'registry/default/examples/dropzone-demo.tsx',
        type: 'registry:example',
      },
    ],
  },
]

registry/index.ts

import { type Registry, type RegistryItem } from 'shadcn/schema'
import { examples } from '@/registry/examples'
import { blocks } from './blocks'
import { clients } from './clients'

export const registry = {
  name: 'Elements',
  homepage: 'https://tryelements.dev',
  items: [
    ...blocks,
    ...clients,
    ...examples,  // Internal use only
  ],
} satisfies Registry

---

3. The __registry__ Pattern

Purpose

The __registry__/index.tsx file is AUTO-GENERATED and used for preview components in documentation.

scripts/build-registry.mts

import { registry } from '../registry/index'

// 1. Write public/r/registry.json (without examples)
const cleanedRegistry = {
  $schema: 'https://ui.shadcn.com/schema/registry.json',
  ...registry,
  items: registry.items.filter((item) => item.type !== 'registry:example'),
}
fs.writeFileSync('public/r/registry.json', JSON.stringify(cleanedRegistry, null, 2))

// 2. Generate __registry__/index.tsx for ComponentPreview
const registryIndex = `
// @ts-nocheck
// This file is autogenerated by scripts/build-registry.mts
import * as React from "react"

export const Index = {
  "default": {
    ${registry.items
      .filter((item) => item.type === 'registry:example')
      .map((item) => {
        const componentFile = item.files.find((file) => file.path.endsWith('.tsx'))
        return `
    "${item.name}": {
      component: React.lazy(() => import("@/${componentFile.path}")),
    }`
      })}
  },
} as const
`
fs.writeFileSync('__registry__/index.tsx', registryIndex)

How It's Used in Docs

// components/component-preview.tsx
import { Index } from '@/__registry__'

export function ComponentPreview({ name }) {
  const Component = Index.default[name]?.component

  return (
    <Suspense fallback={<div>Loading...</div>}>
      <Component />
    </Suspense>
  )
}

---

4. Import Patterns in Registry Files

In Registry Components

// registry/default/blocks/dropzone/components/dropzone.tsx

// ✅ Import from registry using @/registry
import { useSupabaseUpload } from '@/registry/default/blocks/dropzone/hooks/use-supabase-upload'
import { Button } from '@/registry/default/components/ui/button'

// ✅ Import utilities from lib
import { cn } from '@/lib/utils'

In Example/Demo Components

// registry/default/examples/dropzone-demo.tsx

// ✅ Import the actual registry component
import { Dropzone } from '@/registry/default/blocks/dropzone/components/dropzone'
import { useSupabaseUpload } from '@/registry/default/blocks/dropzone/hooks/use-supabase-upload'

export default function DropzoneDemo() {
  const props = useSupabaseUpload({ bucketName: 'test' })
  return <Dropzone {...props} />
}

---

5. Multi-Framework Support Pattern

The Problem

You want dropzone to work with Next.js, React, TanStack, etc.

The Solution

1. Create framework-agnostic component in registry/default/blocks/dropzone/
2. Create framework-specific clients in registry/default/clients/[framework]/
3. Use registryItemAppend() to combine them

Result

• dropzone-nextjs = dropzone + supabase-client-nextjs
• dropzone-react = dropzone + supabase-client-react
• dropzone-tanstack = dropzone + supabase-client-tanstack

All created automatically by the combine() function!

---

6. Component File Organization

Inside a Block Directory

registry/default/blocks/dropzone/
├── registry-item.json       # Manifest
├── components/              # React components
│   └── dropzone.tsx
├── hooks/                   # Custom hooks
│   └── use-supabase-upload.ts
└── lib/                     # Utilities (optional)
    └── utils.ts

Client Directory

registry/default/clients/nextjs/
├── registry-item.json
└── lib/
    └── supabase/
        ├── client.ts        # Browser client
        ├── server.ts        # Server client
        └── middleware.ts    # Middleware

---

7. registry-item.json Patterns

Component Block

{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "dropzone",
  "type": "registry:component",
  "title": "Dropzone (File Upload)",
  "description": "Displays a control for easier uploading of files",
  "registryDependencies": ["button"],
  "dependencies": ["react-dropzone", "lucide-react"],
  "files": [
    {
      "path": "registry/default/blocks/dropzone/components/dropzone.tsx",
      "type": "registry:component"
    },
    {
      "path": "registry/default/blocks/dropzone/hooks/use-supabase-upload.ts",
      "type": "registry:hook"
    }
  ]
}

Client Library

{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "supabase-client-nextjs",
  "type": "registry:lib",
  "title": "Supabase Client for Next.js",
  "registryDependencies": [],
  "dependencies": ["@supabase/ssr@latest", "@supabase/supabase-js@latest"],
  "envVars": {
    "NEXT_PUBLIC_SUPABASE_URL": "",
    "NEXT_PUBLIC_SUPABASE_ANON_KEY": ""
  },
  "files": [
    {
      "path": "registry/default/clients/nextjs/lib/supabase/client.ts",
      "type": "registry:lib"
    }
  ]
}

---

8. What We Need to Change in Elements

Structure Changes

1. Flatten blocks: Move from registry/default/blocks/clerk/clerk-sign-in/ to registry/default/blocks/clerk-sign-in/
2. Create organizer files: Add blocks.ts, examples.ts
3. Separate examples: Move demo components to registry/default/examples/
4. Update index.ts: Import from organizer files instead of auto-scanning

File Changes

1. registry/blocks.ts: Import all block registry-item.json files
2. registry/examples.ts: Define demo components
3. registry/index.ts: Combine all imports
4. scripts/build-registry.ts: Generate __registry__/index.tsx

Component Changes

1. Ensure all imports use @/registry/default/blocks/[component]/
2. No relative imports
3. External deps use @/components/ui/ or @/lib/

---

9. Build Process

Steps

1. Developer creates component in registry/default/blocks/my-component/
2. Add to blocks.ts: Import the registry-item.json
3. Run build: bun run build:registry
4. Outputs:
   • public/r/registry.json - Main index (without examples)
   • public/r/[name].json - Individual component files
   • __registry__/index.tsx - Preview component loader

---

10. Key Takeaways

✅ FLAT structure - No provider subdirectories in blocks ✅ Organizer files - blocks.ts, examples.ts separate concerns ✅ Auto-generation - __registry__/index.tsx generated for previews ✅ Examples separate - Demo components in their own directory ✅ JSON imports - Direct import with with { type: 'json' } ✅ Type safety - Use satisfies Registry for type checking

---

Next Steps for Elements

1. Restructure to flat blocks
2. Create blocks.ts and examples.ts
3. Update build script to generate registry/index.tsx
4. Create example components for documentation previews
5. Test build and verify all 64 components work

---

This structure is production-proven by Supabase and follows shadcn best practices exactly.

║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║
║