### Install Dependencies and Start Server

Source: https://github.com/birobirobiro/awesome-shadcn-ui/blob/main/DEVELOPMENT.md

Commands to install project dependencies and start the development server. Also includes the command to build for production.

```bash
# Install dependencies
npm install

# Start development server
npm run dev

# Build for production
npm run build
```

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

### WebsitePreview Example

Source: https://github.com/birobirobiro/awesome-shadcn-ui/blob/main/_autodocs/data-structures.md

An example of the WebsitePreview object, showing extracted metadata for a website.

```json
{
  "title": "shadcn/ui",
  "description": "Beautifully designed components built with Radix UI and Tailwind CSS.",
  "image": "https://ui.shadcn.com/og.png",
  "url": "https://ui.shadcn.com"
}
```

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

### Start GitHub Device Flow API

Source: https://github.com/birobirobiro/awesome-shadcn-ui/blob/main/_autodocs/quick-reference.md

Initiates the GitHub device flow for authentication. Requires a JSON payload with the action 'start'.

```bash
curl -X POST /api/github/device-flow \
  -H "Content-Type: application/json" \
  -d '{"action": "start"}'
```

```json
{
  "device_code": "Vy2ZwJRvHaJ...",
  "user_code": "WDJB-MJHT",
  "verification_uri": "https://github.com/login/device",
  "expires_in": 900,
  "interval": 5
}
```

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

### CategoryResource Example

Source: https://github.com/birobirobiro/awesome-shadcn-ui/blob/main/_autodocs/data-structures.md

An example of the CategoryResource object, demonstrating how resources are organized into categories like 'Libs and Components' and 'Tools'.

```json
{
  "Libs and Components": [
    { id: "shadcn-ui", name: "shadcn/ui", ... },
    { id: "radix-ui", name: "Radix UI", ... }
  ],
  "Tools": [
    { id: "storybook", name: "Storybook", ... }
  ]
}
```

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

### Resource JSON Example

Source: https://github.com/birobirobiro/awesome-shadcn-ui/blob/main/_autodocs/data-structures.md

Provides an example of a Resource object in JSON format. This illustrates the expected data for each field, including generated IDs and date formats.

```json
{
  "id": "shadcn-ui-blocks",
  "name": "shadcn-blocks",
  "url": "https://ui.shadcn.com/blocks",
  "description": "Official pre-made customizable components.",
  "category": "Libs and Components",
  "date": "2024-12-27T12:56:05.000Z",
  "order": 42
}
```

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

### DeviceFlowResponse Example

Source: https://github.com/birobirobiro/awesome-shadcn-ui/blob/main/_autodocs/data-structures.md

An example JSON object representing a typical response from GitHub's device flow authorization. This shows the format and sample values for each field.

```json
{
  "device_code": "Vy2ZwJRvHaJ...",
  "user_code": "WDJB-MJHT",
  "verification_uri": "https://github.com/login/device",
  "expires_in": 900,
  "interval": 5
}
```

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

### Project Development Environment Setup

Source: https://github.com/birobirobiro/awesome-shadcn-ui/blob/main/DEVELOPMENT.md

Confirms that no specific environment variables are required for development, as all configuration is managed within `src/lib/config.ts`.

```bash
# No environment variables required
# All config is in src/lib/config.ts
```

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

### Environment Configuration for GitHub Token

Source: https://github.com/birobirobiro/awesome-shadcn-ui/blob/main/_autodocs/api-routes.md

Example of the required `GITHUB_TOKEN` environment variable in `.env.local` for authentication.

```bash
GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

```

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

### useWebsitePreview Hook Usage Example

Source: https://github.com/birobirobiro/awesome-shadcn-ui/blob/main/_autodocs/hooks-overview.md

Demonstrates how to use the useWebsitePreview hook to fetch and display website preview data. Handles loading and error states.

```tsx
import { useWebsitePreview } from '@/hooks/use-website-preview'

export function ResourcePreview({ url }: { url: string }) {
  const { preview, isLoading, error } = useWebsitePreview(url)

  if (isLoading) return <p>Loading preview...</p>
  if (error) return <p>Could not load preview</p>
  
  return (
    <div>
      <img src={preview?.image} alt={preview?.title} />
      <h3>{preview?.title}</h3>
      <p>{preview?.description}</p>
    </div>
  )
}
```

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

### Generated PR Example

Source: https://github.com/birobirobiro/awesome-shadcn-ui/blob/main/_autodocs/configuration.md

An example of a fully generated pull request body, including header, description, category selection, additional details, and checklist.

```markdown
---
name: "feat: Add new awesome resource"
about: "Propose adding a new awesome resource related to shadcn/ui"
labels:
  - feature
---

## Describe the awesome resource you want to add

**What is it?**
A cool new shadcn component library

## **Which section does it belong to?**
- [x] Libs and Components

## **Additional details (optional)**
Resource URL: https://example.com

## **Checklist**
- [x] Resource is automatically sorted alphabetically within its section.
- [x] Duplicate checking is performed automatically.
- [x] Table formatting is handled automatically.
- [x] Includes a valid and working link to the resource.
- [x] Automatically assigned the correct section to the resource.
```

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

### GitHub OAuth Device Flow - Start Action Response (200 OK)

Source: https://github.com/birobirobiro/awesome-shadcn-ui/blob/main/_autodocs/api-routes.md

Successful response when starting the GitHub OAuth device flow. Contains codes and URIs for user authorization.

```json
{
  "device_code": "string",
  "user_code": "string",
  "verification_uri": "https://github.com/login/device",
  "expires_in": 900,
  "interval": 5
}
```

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

### SubmissionData JSON Example

Source: https://github.com/birobirobiro/awesome-shadcn-ui/blob/main/_autodocs/data-structures.md

An example of the JSON payload representing data for a new resource submission. Fields like name, description, url, and category must adhere to specific validation rules.

```json
{
  "name": "shadcn-calendar",
  "description": "Calendar component built on shadcn/ui with Tailwind CSS",
  "url": "https://github.com/user/shadcn-calendar",
  "category": "Libs and Components"
}
```

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

### GitHub OAuth Device Flow Initiation

Source: https://github.com/birobirobiro/awesome-shadcn-ui/blob/main/DEVELOPMENT.md

Illustrates the initial steps for initiating the GitHub OAuth device flow. This involves starting the flow to obtain a user code and verification URI.

```typescript
// 1. Start device flow
const { userCode, verificationUri } = await startDeviceFlow();

// 2. User authorizes on GitHub
// 3. Poll for access token
// 4. Get user info and create authenticated Octokit
```

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

### Grouping Resources by Category

Source: https://github.com/birobirobiro/awesome-shadcn-ui/blob/main/_autodocs/data-structures.md

A TypeScript example demonstrating how to group an array of resources into a CategoryResource object using the reduce method.

```typescript
const grouped = resources.reduce((acc, resource) => {
  if (!acc[resource.category]) acc[resource.category] = []
  acc[resource.category].push(resource)
  return acc
}, {} as CategoryResource)
```

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

### POST /api/github/device-flow

Source: https://github.com/birobirobiro/awesome-shadcn-ui/blob/main/_autodocs/COVERAGE.md

Initiates the GitHub device flow for authentication. It supports starting the flow and polling for authorization status.

```APIDOC
## POST /api/github/device-flow

### Description
Initiates the GitHub device flow for authentication. This endpoint allows users to start the OAuth device flow and poll for the authorization status.

### Method
POST

### Endpoint
/api/github/device-flow

### Parameters
#### Request Body
- **action** (string) - Required - Specifies the action to perform. Must be either 'start' or 'poll'.

### Request Example
```json
{
  "action": "start"
}
```

### Response
#### Success Response (200)
- **DeviceFlowResponse** (object) - Contains details for the device flow, such as user code and verification URI.
- **GitHubAuthState** (object) - Represents the current authentication state.

#### Response Example
```json
{
  "device_code": "...",
  "user_code": "ABCDEF",
  "verification_uri": "https://github.com/login/device",
  "expires_in": 900,
  "interval": 5
}
```

### Error Handling
- Documented error codes and their meanings are provided.
```

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

### Submit Resource Form Example

Source: https://github.com/birobirobiro/awesome-shadcn-ui/blob/main/_autodocs/hooks-overview.md

A React component demonstrating how to use the usePRSubmission hook to create a form for submitting new resources. It handles form submission, displays loading states, and shows errors.

```tsx
import { usePRSubmission } from '@/hooks/use-pr-submission'

export function SubmitResourceForm() {
  const { submitPR, isSubmitting, error, submissionStatus } = usePRSubmission()

  const handleSubmit = async (formData: SubmissionData) => {
    const result = await submitPR(formData)
    if (result.success) {
      console.log('PR created:', result.prUrl)
    } else {
      console.error('Submission failed:', result.error)
    }
  }

  return (
    <form onSubmit={(e) => {
      e.preventDefault()
      handleSubmit({
        name: 'My Component',
        description: 'A cool component',
        url: 'https://example.com',
        category: 'Components'
      })
    }}>
      <button type="submit" disabled={isSubmitting}>
        {isSubmitting ? submissionStatus : 'Submit'}
      </button>
      {error && <p>{error}</p>}
    </form>
  )
}
```

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

### useGitHubAuth

Source: https://github.com/birobirobiro/awesome-shadcn-ui/blob/main/_autodocs/quick-reference.md

Hook for handling GitHub authentication, including starting the device flow, logging out, and creating an authenticated Octokit client.

```APIDOC
## useGitHubAuth

### Description
Provides functionality for GitHub authentication, including initiating the device flow, managing authentication state, and logging out.

### Import
```typescript
import { useGitHubAuth } from '@/hooks/use-github-auth'
```

### Return Value
```typescript
{
  authState: GitHubAuthState
  isLoading: boolean
  error: string | null
  startDeviceFlow: () => Promise<{ success: boolean; userCode?: string; verificationUri?: string }>
  logout: () => void
  stopPolling: () => void
  createAuthenticatedOctokit: () => Octokit | null
}
```

### Exported Types
- `GitHubAuthState`
- `GitHubUser`
- `DeviceFlowResponse`
- `UseGitHubAuthReturn`
```

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

### GitHub Device Flow Start Response

Source: https://github.com/birobirobiro/awesome-shadcn-ui/blob/main/_autodocs/INDEX.md

Response structure when initiating the GitHub device flow. Contains codes and URLs for user authorization and polling.

```typescript
{
  device_code: string         // For polling
  user_code: string           // Show to user
  verification_uri: string    // GitHub authorization URL
  expires_in: number          // Seconds until expiration (900)
  interval: number            // Polling interval in seconds (5)
}
```

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

### Client-Side GitHub Authentication Hook Usage

Source: https://github.com/birobirobiro/awesome-shadcn-ui/blob/main/_autodocs/api-routes.md

Example of using the `useGitHubAuth` hook to initiate and manage the GitHub device flow on the client side.

```tsx
const { authState, startDeviceFlow } = useGitHubAuth()

// Step 1: Start flow
const result = await startDeviceFlow()
// Display result.userCode and result.verificationUri

// Step 2: Hook polls automatically at specified interval
// Step 3: On success, authState.isAuthenticated becomes true
```

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

### GitHub OAuth Device Flow - Start Action Request Body

Source: https://github.com/birobirobiro/awesome-shadcn-ui/blob/main/_autodocs/api-routes.md

Use this JSON payload to initiate the GitHub OAuth device flow.

```json
{
  "action": "start"
}
```

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

### Set GITHUB_TOKEN Environment Variable

Source: https://github.com/birobirobiro/awesome-shadcn-ui/blob/main/_autodocs/configuration.md

Example of how to set the required GITHUB_TOKEN environment variable for backend operations. This token is a GitHub personal access token.

```bash
GITHUB_TOKEN=ghp_1234567890abcdefghijklmnopqrstuvwxyz
```

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

### Octokit Debugging with Authenticated User

Source: https://github.com/birobirobiro/awesome-shadcn-ui/blob/main/_autodocs/quick-reference.md

Create an authenticated Octokit client using `useGitHubAuth` and make a request to get the authenticated user's information. This helps verify authentication and API access.

```typescript
const octokit = useGitHubAuth().createAuthenticatedOctokit()
octokit.rest.users.getAuthenticated().then(console.log)
```

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

### Example Usage of Generic useDebounce Hook

Source: https://github.com/birobirobiro/awesome-shadcn-ui/blob/main/_autodocs/data-structures.md

Demonstrates the usage of the generic `useDebounce` hook with a string type. The debounced output maintains the original string type.

```typescript
const query: string = "search"
const debouncedQuery = useDebounce(query, 300)
// debouncedQuery is type: string
```

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

### useBookmarks Hook Usage Example

Source: https://github.com/birobirobiro/awesome-shadcn-ui/blob/main/_autodocs/hooks-overview.md

Demonstrates how to use the useBookmarks hook in a React component to create a bookmark button. It utilizes the `isBookmarked` and `toggleBookmark` functions to manage the bookmark state and UI.

```tsx
import { useBookmarks } from '@/hooks/use-bookmark'

export function BookmarkButton({ itemId }: { itemId: string }) {
  const { isBookmarked, toggleBookmark } = useBookmarks()

  return (
    <button onClick={() => toggleBookmark(itemId)}>
      {isBookmarked(itemId) ? '★ Bookmarked' : '☆ Bookmark'}
    </button>
  )
}
```

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

### Example JSON API Error Response

Source: https://github.com/birobirobiro/awesome-shadcn-ui/blob/main/_autodocs/data-structures.md

An example of an API error response in JSON format.

```json
{
  "error": "GitHub API error: 401 - Unauthorized"
}
```

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

### PRSubmissionResult Error Example

Source: https://github.com/birobirobiro/awesome-shadcn-ui/blob/main/_autodocs/data-structures.md

Example JSON representing a failed pull request submission. Includes the success status and a human-readable error message.

```json
{
  "success": false,
  "error": "Resource \"my-component\" already exists in \"Libs and Components\"."
}
```

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

### Import and Use Custom Configuration

Source: https://github.com/birobirobiro/awesome-shadcn-ui/blob/main/_autodocs/configuration.md

Illustrates how to import and utilize custom configurations, such as new error messages, within your application code. Ensure the configuration is imported from '@/lib/config'.

```typescript
import { ERROR_MESSAGES, PR_TEMPLATE } from '@/lib/config'

// Use in code
throw new Error(ERROR_MESSAGES.NEW_ERROR)
```

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

### useWebsitePreview

Source: https://github.com/birobirobiro/awesome-shadcn-ui/blob/main/_autodocs/quick-reference.md

Hook for fetching and displaying a website preview, including title, description, and image.

```APIDOC
## useWebsitePreview

### Description
Fetches and provides data for a website preview, such as title, description, and image, given a URL.

### Import
```typescript
import { useWebsitePreview } from '@/hooks/use-website-preview'
```

### Usage
```typescript
const { preview, isLoading, error } = useWebsitePreview(url: string)
```

### Types
- `WebsitePreview` - { title, description, image, url }
```

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

### Project Structure Overview

Source: https://github.com/birobirobiro/awesome-shadcn-ui/blob/main/_autodocs/architecture.md

Illustrates the directory layout for a Next.js application, including the app router, components, hooks, and utility libraries.

```tree
src/
├── app/                          # Next.js App Router (pages & layouts)
│   ├── api/                      # Backend API routes (server-only)
│   │   ├── github/
│   │   │   ├── callback/route.ts # Legacy OAuth callback
│   │   │   └── device-flow/route.ts # Device flow auth endpoint
│   │   └── submit-resource/route.ts # PR submission endpoint
│   ├── [...not-found]/page.tsx   # 404 page
│   ├── bookmarks/                # Bookmarks feature pages
│   ├── categories/               # Category listing pages
│   ├── globals.css              # Global styles
│   ├── layout.tsx               # Root layout wrapper
│   ├── page.tsx                 # Home page
│   ├── error.tsx                # Error boundary
│   └── not-found.tsx            # 404 boundary
├── components/                   # React components
│   ├── ui/                       # shadcn/ui components (copied)
│   ├── layout/                   # Layout components
│   │   ├── footer.tsx
│   │   ├── header.tsx
│   │   └── page-header.tsx
│   ├── category-page-content.tsx # Category page display logic
│   ├── cta-submit.tsx            # Submit button/dialog
│   ├── github-stars.tsx          # GitHub stars display
│   ├── hero.tsx                  # Hero section
│   ├── home-content.tsx          # Home page content
│   ├── item-card.tsx             # Resource card component
│   ├── item-grid.tsx             # Grid layout for resources
│   ├── item-page-content.tsx     # Single resource detail page
│   ├── items-list.tsx            # List layout for resources
│   ├── pagination-controls.tsx   # Pagination UI
│   ├── pr-submission-dialog.tsx  # PR submission form & dialog
│   ├── search-filter-controls.tsx # Search & filter controls
│   ├── sort.tsx                  # Sorting UI
│   ├── sponsor-card.tsx          # Sponsor display
│   ├── sponsors/                 # Sponsor logos
│   ├── sponsorship.tsx           # Sponsorship section
│   ├── theme-toggle.tsx          # Dark mode toggle
│   └── logo.tsx                  # Logo component
├── hooks/                        # Custom React hooks
│   ├── use-bookmark.ts          # Bookmark management (localStorage)
│   ├── use-debounce.ts          # Debounce hook
│   ├── use-github-auth.ts       # GitHub OAuth device flow
│   ├── use-mobile.ts            # Mobile breakpoint detection
│   ├── use-pr-submission.ts     # PR creation flow
│   ├── use-readme.ts            # README parsing & fetching
│   └── use-website-preview.ts   # Website metadata fetching
├── lib/                         # Utilities and configuration
│   ├── config.ts               # Centralized config (GitHub, PR template, messages)
│   ├── compose-refs.ts         # Ref composition utility
│   ├── slugs.ts                # URL slug generation
│   └── utils.ts                # CSS class merging, date formatting
├── providers/                   # React context providers
│   ├── providers.tsx           # Combined providers wrapper
│   └── theme-provider.tsx      # Theme (dark/light) provider
└── ...config files             # Next.js, TypeScript, Tailwind config

```

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

### Client-Side Usage with usePRSubmission Hook

Source: https://github.com/birobirobiro/awesome-shadcn-ui/blob/main/_autodocs/api-routes.md

Example of how to use the `usePRSubmission` hook in a React component to submit a new resource.

```tsx
const { submitPR, isSubmitting, error } = usePRSubmission()

const result = await submitPR({
  name: 'My Component',
  description: 'A cool shadcn component',
  url: 'https://example.com',
  category: 'Libs and Components'
})

if (result.success) {
  window.open(result.prUrl, '_blank')
}

```

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

### Import fetchAndParseReadme Function

Source: https://github.com/birobirobiro/awesome-shadcn-ui/blob/main/_autodocs/quick-reference.md

Import the fetchAndParseReadme function from the '@/hooks/use-readme' module. This utility function fetches and parses the README.md file, caching results for 30 minutes.

```typescript
import { fetchAndParseReadme } from '@/hooks/use-readme'
```

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

### Global State with ThemeProvider

Source: https://github.com/birobirobiro/awesome-shadcn-ui/blob/main/_autodocs/architecture.md

Explains the usage of the ThemeProvider from next-themes for managing application theme, which is persisted to localStorage.

```typescript
ThemeProvider (next-themes)
  ├─ Provides theme: 'light' | 'dark'
  ├─ Persists to localStorage: 'theme'
  └─ All components can access via useTheme()
```

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

### Submit Resource API Request

Source: https://github.com/birobirobiro/awesome-shadcn-ui/blob/main/_autodocs/quick-reference.md

Submits a new resource to the Awesome Shadcn UI project. The request body must include name, description, URL, and category.

```bash
curl -X POST /api/submit-resource \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Component",
    "description": "A cool component",
    "url": "https://example.com",
    "category": "Libs and Components"
  }'
```

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

### fetchAndParseReadme

Source: https://github.com/birobirobiro/awesome-shadcn-ui/blob/main/_autodocs/quick-reference.md

Asynchronously fetches and parses the README.md file, extracting markdown table resources.

```APIDOC
## fetchAndParseReadme

### Description
Fetches the README.md file, parses markdown tables within it, and returns a list of resources. The data is cached for 30 minutes.

### Import
```typescript
import { fetchAndParseReadme } from '@/hooks/use-readme'
```

### Usage
```typescript
const resources = await fetchAndParseReadme(): Promise<Resource[]>
```

### Features
- Caches for 30 minutes
- Parses markdown tables from README.md
- Returns `Resource[]` with unique IDs

### Exported Types
- `Resource` - Full resource object
```

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

### Fetch and Parse README

Source: https://github.com/birobirobiro/awesome-shadcn-ui/blob/main/_autodocs/INDEX.md

Asynchronously fetches and parses the README.md file to extract resource information. Includes caching for performance.

```APIDOC
## fetchAndParseReadme()

### Description
Fetches and parses the README.md file to extract resources. This asynchronous function utilizes caching to improve performance.

### Function Signature
fetchAndParseReadme()

### Parameters
(No parameters are explicitly documented for this function)

### Return Value
- Resource[]: An array of resources parsed from the README.md.

### Caching
- Cache Duration: 30 minutes

### Data Source
- GitHub README.md (authoritative)

### Parsing Logic
- Markdown table is parsed into a Resource[] array.
- Unique IDs are generated with collision detection.
```

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

### Import useWebsitePreview Hook

Source: https://github.com/birobirobiro/awesome-shadcn-ui/blob/main/_autodocs/quick-reference.md

Import the useWebsitePreview hook from the '@/hooks/use-website-preview' module. This hook fetches and processes website preview data for a given URL.

```typescript
import { useWebsitePreview } from '@/hooks/use-website-preview'
```

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

### Handle Errors with Error Messages

Source: https://github.com/birobirobiro/awesome-shadcn-ui/blob/main/_autodocs/configuration.md

Example of catching an error and returning a JSON response with a predefined error message. Ensures consistent error reporting.

```typescript
catch (error: any) {
  return NextResponse.json(
    { error: ERROR_MESSAGES.GITHUB_API },
    { status: 500 }
  )
}
```

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

### Root Layout Structure

Source: https://github.com/birobirobiro/awesome-shadcn-ui/blob/main/_autodocs/architecture.md

Illustrates the basic file structure for the root layout, including header, footer, and the main page content area.

```typescript
layout.tsx (Root layout)
  ├─ header.tsx (Navigation + Logo)
  ├─ page.tsx (or category/[id]/page.tsx)
  │   ├─ home-content.tsx (or category-page-content.tsx)
  │   │   ├─ search-filter-controls.tsx
  │   │   ├─ sort.tsx
  │   │   ├─ item-grid.tsx or items-list.tsx
  │   │   │   └─ item-card.tsx (repeats for each resource)
  │   │   │       └─ pr-submission-dialog.tsx (modal)
  │   │   └─ pagination-controls.tsx
  │   └─ hero.tsx (home only)
  └─ footer.tsx (Navigation + Legal)
```

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

### Development Environment Variables

Source: https://github.com/birobirobiro/awesome-shadcn-ui/blob/main/_autodocs/architecture.md

Use this configuration for local development. It is git-ignored to prevent accidental exposure of sensitive tokens.

```bash
# .env.local (git-ignored)
GITHUB_TOKEN=ghp_...
```

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

### Display Submission Status in React

Source: https://github.com/birobirobiro/awesome-shadcn-ui/blob/main/_autodocs/configuration.md

Example of conditionally rendering a paragraph element with the current submission status message. This is useful for providing real-time feedback to the user.

```tsx
const { submissionStatus } = usePRSubmission()

return (
  <div>
    {submissionStatus && <p>{submissionStatus}</p>}
  </div>
)
```

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

### Fetch and Parse README Data

Source: https://github.com/birobirobiro/awesome-shadcn-ui/blob/main/_autodocs/00-START-HERE.md

Use the `fetchAndParseReadme` function to retrieve and process resource data from the project's README file. This function returns an array of Resource objects.

```typescript
import { fetchAndParseReadme } from '@/hooks/use-readme'

const resources = await fetchAndParseReadme()
// Returns Resource[] with 300+ items from README
```

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

### GitHub OAuth Device Flow - Poll Action Request Body

Source: https://github.com/birobirobiro/awesome-shadcn-ui/blob/main/_autodocs/api-routes.md

Use this JSON payload with the device_code obtained from the 'start' action to poll for token acquisition.

```json
{
  "action": "poll",
  "device_code": "Vy2ZwJRvHaJ..."
}
```

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

### STATUS_MESSAGES Configuration

Source: https://github.com/birobirobiro/awesome-shadcn-ui/blob/main/_autodocs/quick-reference.md

Contains status messages used to track the progress of the submission flow. These messages inform the user about the current stage, from starting the process to creating a pull request.

```typescript
import { STATUS_MESSAGES } from '@/lib/config'

// Messages: 10 progress messages for submission flow (STARTING, CHECKING_FORK, USING_EXISTING_FORK, CREATING_FORK, VERIFYING_FORK, GETTING_COMMIT, CREATING_BRANCH, READING_README, COMMITTING, CREATING_PR)
```

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

### Submit Resource API

Source: https://github.com/birobirobiro/awesome-shadcn-ui/blob/main/_autodocs/quick-reference.md

This API allows users to submit new resources to the awesome-shadcn-ui project.

```APIDOC
## POST /api/submit-resource

### Description
Submits a new resource to be added to the awesome-shadcn-ui project. This will create a pull request.

### Method
POST

### Endpoint
/api/submit-resource

### Parameters
#### Request Body
- **name** (string) - Required - The display name of the component or library.
- **description** (string) - Required - A brief description of the resource.
- **url** (string) - Required - The HTTP(S) URL of the resource.
- **category** (string) - Required - The category under which the resource should be listed (e.g., "Libs and Components").

### Request Example
```json
{
  "name": "My Component",
  "description": "A cool component",
  "url": "https://example.com",
  "category": "Libs and Components"
}
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the submission was successful.
- **prNumber** (number) - The number of the created pull request.
- **prUrl** (string) - The URL of the created pull request.

#### Response Example
```json
{
  "success": true,
  "prNumber": 123,
  "prUrl": "https://github.com/birobirobiro/awesome-shadcn-ui/pull/123"
}
```

#### Error Response
- **error** (string) - A message describing the error, e.g., if the resource already exists.

#### Error Response Example
```json
{
  "error": "Resource \"My Component\" already exists in \"Libs and Components\"."
}
```
```

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

### Run Development Checks

Source: https://github.com/birobirobiro/awesome-shadcn-ui/blob/main/DEVELOPMENT.md

Commands to execute type checking, linting, and a build check for the project. These are essential for maintaining code quality and ensuring a stable build.

```bash
# Run type checking
npm run type-check

# Run linting
npm run lint

# Build check
npm run build
```

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

### Custom GitHub OAuth Client ID

Source: https://github.com/birobirobiro/awesome-shadcn-ui/blob/main/_autodocs/configuration.md

Example of how to customize the `GITHUB_CONFIG` by providing your own GitHub OAuth App Client ID. Obtain your Client ID from GitHub's Developer settings.

```typescript
export const GITHUB_CONFIG = {
  CLIENT_ID: "YOUR_CLIENT_ID", // Get from GitHub Settings > Developer settings > OAuth Apps
  // ... rest of config
}
```

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

### Poll GitHub Device Flow API

Source: https://github.com/birobirobiro/awesome-shadcn-ui/blob/main/_autodocs/quick-reference.md

Polls the GitHub device flow API to check authentication status. Requires the 'action' set to 'poll' and the 'device_code' obtained from the start flow.

```bash
curl -X POST /api/github/device-flow \
  -H "Content-Type: application/json" \
  -d '{"action": "poll", "device_code": "Vy2ZwJRvHaJ..."}'
```

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

### Import Core Hooks

Source: https://github.com/birobirobiro/awesome-shadcn-ui/blob/main/_autodocs/00-START-HERE.md

Import necessary hooks from the '@/hooks/' directory to utilize their functionalities.

```typescript
import { useGitHubAuth } from '@/hooks/use-github-auth'
import { usePRSubmission } from '@/hooks/use-pr-submission'
import { useBookmarks } from '@/hooks/use-bookmark'
```

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

### Entry Format in README

Source: https://github.com/birobirobiro/awesome-shadcn-ui/blob/main/_autodocs/api-routes.md

The markdown table row format for a new resource entry in the README.md file.

```markdown
| Component Name | Component description | [Link](https://example.com) | 2024-01-15 |

```

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

### Submit Resource API Error Response - Could Not Fetch README (500)

Source: https://github.com/birobirobiro/awesome-shadcn-ui/blob/main/_autodocs/api-routes.md

Returned when the server fails to fetch the README.md file.

```json
{
  "error": "Could not fetch README"
}
```

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

### Submit Resource Input Structure

Source: https://github.com/birobirobiro/awesome-shadcn-ui/blob/main/_autodocs/INDEX.md

Defines the expected input format for submitting a new resource. Requires name, description, URL, and category.

```typescript
{
  name: string                // Resource name
  description: string         // Description
  url: string                 // Valid HTTP(S) URL
  category: string            // Exact category match
}
```

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

### Module Dependency Map

Source: https://github.com/birobirobiro/awesome-shadcn-ui/blob/main/_autodocs/architecture.md

Visualizes the relationships between different modules and external libraries within the project. Shows how components, hooks, API routes, and utility libraries interact.

```tree
/components
  ├─ /ui (shadcn/ui exports)
  └─ /lib/utils (cn, formatResourceDate)

/hooks
  ├─ /lib/config (GITHUB_CONFIG, ERROR_MESSAGES, etc.)
  ├─ /lib/slugs (titleToSlug)
  └─ @octokit/rest (GitHub API client)

/app/api
  ├─ /lib/config
  ├─ @octokit/rest
  └─ /hooks/use-readme (in some routes)

/lib
  └─ date-fns (date formatting)
```

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

### Bookmarks Management

Source: https://github.com/birobirobiro/awesome-shadcn-ui/blob/main/_autodocs/INDEX.md

Manages client-side bookmarking of favorite resources using localStorage for persistence.

```APIDOC
## useBookmarks()

### Description
A hook for managing user bookmarks (favorite resources) with client-side persistence using localStorage.

### Hook Signature
useBookmarks()

### Parameters
(No parameters are explicitly documented for this hook)

### Storage
- **Type:** localStorage
- **Key:** "bookmarkedItems" (stores a JSON array of resource IDs)

### Features
- **Persistence:** Bookmarks survive page refreshes.
- **Debounce:** Implements a 300ms debounce on interactions to prevent accidental double-clicks.
```

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

### Import useGitHubAuth Hook

Source: https://github.com/birobirobiro/awesome-shadcn-ui/blob/main/_autodocs/quick-reference.md

Import the useGitHubAuth hook from the '@/hooks/use-github-auth' module. This hook manages GitHub authentication, including device flow, logout, and creating authenticated Octokit instances.

```typescript
import { useGitHubAuth } from '@/hooks/use-github-auth'
```

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

### Fetch and Parse README Resources

Source: https://github.com/birobirobiro/awesome-shadcn-ui/blob/main/_autodocs/INDEX.md

Fetches and parses README content to retrieve a list of resources. The data is cached for 30 minutes to reduce API calls.

```tsx
import { fetchAndParseReadme } from '@/hooks/use-readme'

const resources = await fetchAndParseReadme()
// Returns Resource[] array (cached for 30 min)

const libs = resources.filter(r => r.category === 'Libs and Components')
```

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

### Submit Resource API Error Response - Server Configuration Error (500)

Source: https://github.com/birobirobiro/awesome-shadcn-ui/blob/main/_autodocs/api-routes.md

Returned for general server-side configuration issues.

```json
{
  "error": "Server configuration error"
}
```

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

### Usage of fetchAndParseReadme Function

Source: https://github.com/birobirobiro/awesome-shadcn-ui/blob/main/_autodocs/quick-reference.md

The fetchAndParseReadme function asynchronously fetches and parses markdown tables from README.md, returning an array of Resource objects. It includes caching for improved performance.

```typescript
const resources = await fetchAndParseReadme(): Promise<Resource[]>
```

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

### Manage Resource Bookmarks

Source: https://github.com/birobirobiro/awesome-shadcn-ui/blob/main/_autodocs/INDEX.md

Provides functionality to check if a resource is bookmarked and to toggle the bookmark status. This uses local storage for persistence.

```tsx
import { useBookmarks } from '@/hooks/use-bookmark'

const { isBookmarked, toggleBookmark } = useBookmarks()

<button onClick={() => toggleBookmark(resource.id)}>
  {isBookmarked(resource.id) ? '★' : '☆'}
</button>
```

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

### Authenticate User with GitHub

Source: https://github.com/birobirobiro/awesome-shadcn-ui/blob/main/_autodocs/INDEX.md

Initiates the GitHub device flow for user authentication if the user is not already authenticated. Displays the user code and verification URI for the user to complete the authentication process.

```tsx
import { useGitHubAuth } from '@/hooks/use-github-auth'

const { authState, startDeviceFlow } = useGitHubAuth()

if (!authState.isAuthenticated) {
  await startDeviceFlow()
  // Display authState.userCode and authState.verificationUri
}
```

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

### Usage of useWebsitePreview Hook

Source: https://github.com/birobirobiro/awesome-shadcn-ui/blob/main/_autodocs/quick-reference.md

The useWebsitePreview hook takes a URL and returns preview data including title, description, image, and the original URL, along with loading and error states.

```typescript
const { preview, isLoading, error } = useWebsitePreview(url: string)
```

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

### GITHUB_CONFIG Configuration Object

Source: https://github.com/birobirobiro/awesome-shadcn-ui/blob/main/_autodocs/INDEX.md

Configuration settings for GitHub integration, including client ID, repository details, and API endpoints.

```typescript
{
  CLIENT_ID: "Ov23lizgfZ4yKq0NxcTm"
  REPO_OWNER: "birobirobiro"
  REPO_NAME: "awesome-shadcn-ui"
  DEVICE_FLOW_URL: "https://github.com/login/device/code"
  ACCESS_TOKEN_URL: "https://github.com/login/oauth/access_token"
  SCOPES: ["repo"]
  FORK_CREATION_DELAY: 5000
}
```

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

### Hook Dependencies for Home Content

Source: https://github.com/birobirobiro/awesome-shadcn-ui/blob/main/_autodocs/architecture.md

Outlines the hooks used in the home content component for data fetching, search debouncing, bookmark status, and mobile layout.

```typescript
home-content.tsx or category-page-content.tsx
  ├─ useReadme (fetch resources)
  ├─ useDebounce (search)
  ├─ useBookmarks (bookmark status)
  └─ useMobile (layout switching)
```

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

### POST /api/submit-resource

Source: https://github.com/birobirobiro/awesome-shadcn-ui/blob/main/_autodocs/api-routes.md

Creates a pull request to add a new resource to the awesome-shadcn-ui README.md. This endpoint is typically used via the `usePRSubmission` hook on the client-side.

```APIDOC
## POST /api/submit-resource

### Description
Creates a pull request to add a new resource to the awesome-shadcn-ui README.md.

### Method
POST

### Endpoint
/api/submit-resource

### Parameters
#### Request Body
- **name** (string) - Required - Resource name (1-200 chars)
- **description** (string) - Required - Resource description (1-500 chars)
- **url** (string) - Required - Valid HTTP(S) URL to resource
- **category** (string) - Required - Exact category name from README

### Request Example
```json
{
  "name": "My Component",
  "description": "A cool shadcn component",
  "url": "https://example.com",
  "category": "Libs and Components"
}
```

### Response
#### Success Response (200 OK)
- **success** (boolean) - Always true on success
- **prNumber** (number) - Pull request number
- **prUrl** (string) - Direct link to PR on GitHub

#### Response Example
```json
{
  "success": true,
  "prNumber": 123,
  "prUrl": "https://github.com/birobirobiro/awesome-shadcn-ui/pull/123"
}
```

### Error Responses
- **400 - Missing Fields:**
```json
{
  "error": "All fields are required"
}
```
- **400 - Invalid URL:**
```json
{
  "error": "Invalid URL format"
}
```
- **409 - Duplicate Resource:**
```json
{
  "error": "Resource \"Component Name\" already exists in \"Libs and Components\"."
}
```
- **409 - Category Not Found:**
```json
{
  "error": "Could not find insertion point for category \"Invalid Category\"."
}
```
- **500 - Server Configuration:**
```json
{
  "error": "Server configuration error"
}
```
- **500 - Could Not Fetch README:**
```json
{
  "error": "Could not fetch README"
}
```
- **500 - GitHub API Error:**
```json
{
  "error": "API rate limit exceeded"
}
```

### Authentication
**Required:** `GITHUB_TOKEN` environment variable with `repo` scope.
```