DOCSEARCHbyAlgolia
Submit Docs

21st.dev Documentation

repository·main·Indexed 26 days ago

https://github.com/serafimcloud/21st

An open-source community registry for React UI components built with Tailwind CSS and Radix UI. The documentation covers discovering, publishing, and installing components via npx shadcn, as well as technical details for the backend bundler, including bundleReact(), compileCSS(), and Cloudflare R2 storage integration.

Tokens
7.6K
Snippets
6
Records
48
Agent score
90%

What's inside 21st.dev

  1. Install a component via npx shadcn

    main

    To install a component from 21st.dev into your project, use the npx shadcn command with the component's direct URL. This is the recommended method as it automatically creates necessary files, extends your Tailwind theme, and sets up required global styles.

    Example for installing the shadcn/ui/accordion component:

    npx shadcn@latest add "https://21st.dev/r/shadcn/accordion"

  2. Quality guidelines for featured components

    main

    To increase the chances of your component being featured, follow these standards:

    • Visual Quality: Polished UI/UX that supports both light and dark modes using shadcn's CSS variables (e.g., hsl(var(--background))).
    • Code Structure: Separate component logic from demo content. The code.tsx file should contain only reusable functionality, while demos/ files should use props to showcase the component.
    • Accessibility: Include proper ARIA attributes, support keyboard navigation, and ensure sufficient color contrast.
    • Technical Standards: Use TypeScript, Tailwind CSS, and Radix UI primitives. Minimize external dependencies and ensure responsive behavior.

  4. Set up 21st.dev development environment

    main

    To contribute to the 21st.dev repository, follow these setup steps:

    1. Prerequisites: Ensure you have accounts for Supabase, Clerk, and Cloudflare R2.
    2. Clone & Install: Fork the repo, clone it, and install dependencies using pnpm:
      pnpm install
    3. **Environment Variables**: Create a `.env.local` file in `apps/web` with the following keys:

| Category | Key | Description |
| --- | --- | --- |
| **Supabase** | `NEXT_PUBLIC_SUPABASE_URL` | Supabase project URL |
| | `NEXT_PUBLIC_SUPABASE_KEY` | Supabase public key |
| | `SUPABASE_SERVICE_ROLE_KEY` | Supabase service role key |
| **Clerk** | `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY` | Clerk publishable key |
| | `CLERK_SECRET_KEY` | Clerk secret key |
| | `CLERK_WEBHOOK_SECRET` | Clerk webhook secret |
| **Cloudflare R2** | `NEXT_PUBLIC_CDN_URL` | R2 CDN URL |
| | `R2_ACCESS_KEY_ID` | R2 access key ID |
| | `R2_SECRET_ACCESS_KEY` | R2 secret access key |
| | `NEXT_PUBLIC_R2_ENDPOINT` | R2 endpoint URL |
| **Other** | `NEXT_PUBLIC_APP_URL` | App URL (e.g., https://21st.dev) |
| | `NEXT_PUBLIC_AMPLITUDE_API_KEY` | Amplitude API key |

4. **Run**: Start the development server:
   ```bash
pnpm dev
    pnpm install
# ... after setting up .env.local
pnpm dev

  5. Publish a React component to 21st.dev

    main

    You can publish React components to the 21st.dev registry by visiting the publish page. Components follow a specific lifecycle:

    1. on_review: Initial state; available via direct link but awaiting review.
    2. posted: Passed review; available on your profile and via direct link.
    3. featured: Featured on the homepage and public listings.

    Required File Structure

    To ensure compatibility, organize your component files as follows:

    your-component/                # Root directory
├── code.tsx                  # Main reusable component logic
├── tailwind.config.js        # (Optional) Tailwind configuration
├── globals.css              # (Optional) Global styles
└── demos/                    # Directory for component variations
    ├── default/             # Primary demo (Required)
    │   ├── code.demo.tsx    # Demo implementation
    │   ├── preview.png      # Static preview image
    │   └── video.mp4        # (Optional) Demo video
    └── advanced/            # Additional demos (Optional)
        ├── code.demo.tsx
        ├── preview.png
        └── video.mp4
    your-component/                # How to organize your files
├── code.tsx                  # Main component
├── tailwind.config.js        # Optional Tailwind config
├── globals.css              # Optional global styles
└── demos/                    # Each component can have multiple demos
    ├── default/             # Primary demo (required)
    │   ├── code.demo.tsx    # Demo implementation
    │   ├── preview.png      # Static preview image
    │   └── video.mp4        # Optional demo video
    └── advanced/            # Additional demos (optional)
        ├── code.demo.tsx
        ├── preview.png
        └── video.mp4

  6. Run the web application in development mode

    main

    To start the development server for the web application, use one of the following package manager commands. Once running, the application will be available at http://localhost:3000.

    npm run dev
# or
yarn dev
# or
pnpm dev
# or
bun dev

  7. Use the search-embeddings Edge Function

    main

    The search-embeddings Supabase Edge Function performs vector similarity searches to find components and demos. It uses the HyDE (Hypothetical Document Embeddings) technique to improve search relevance by generating hypothetical search queries based on the user's input and context before performing the embedding search.

    Request Format

    Send a POST request with a JSON body containing:

    • search (string, required): The search query.
    • match_threshold (number, optional): A value between 0.1 and 0.99 to filter results by similarity. Defaults to 0.33.
    • userMessage (string, optional): Additional context from the user to improve HyDE query generation.

    Response Format

    A JSON array of search results. Each result includes similarity scores and metadata retrieved via the match_embeddings_with_details RPC.

    Authentication

    Include the user's Supabase authorization header in the request to ensure proper permissions.

  8. Configure R2 storage environment variables

    main

    The R2 storage client requires the following environment variables to be set for connection and asset delivery:

    • NEXT_PUBLIC_R2_ENDPOINT: The endpoint for the Cloudflare R2 instance.
    • R2_ACCESS_KEY_ID: The access key for R2 credentials.
    • R2_SECRET_ACCESS_KEY: The secret access key for R2 credentials.
    • NEXT_PUBLIC_CDN_URL: The base URL used to construct public URLs for stored HTML files.

  9. Configure environment variables for search_demos_ai_oai_extended

    main

    The search_demos_ai_oai_extended function requires the following environment variables to be set in your Supabase project:

    • OPENAI_API_KEY: Your OpenAI API key used to generate embeddings via the text-embedding-3-small model.
    • SUPABASE_URL: The URL of your Supabase project.
    • SUPABASE_ANON_KEY: The anonymous API key for your Supabase project.

  10. Configure bundle options with BundleOptions

    main

    When using the bundler, provide a BundleOptions object to specify the files to be processed, their dependencies, and styling configurations.

    Key properties:

    • files: A record mapping file paths to their string content (Record<string, string>).
    • dependencies: (Optional) A record mapping package names to versions (Record<string, string>).
    • tailwindConfig: (Optional) The path or content identifier for the Tailwind configuration.
    • globalCss: (Optional) The path or content identifier for global CSS.
    • bundledCss: (Optional) The path or content identifier for bundled CSS.

  11. Start the backend server with startServer()

    main
    The startServer function initializes a Bun server that routes incoming requests through the application's defined routes. It requires a port number as an argument. The function returns the Bun server instance, which can be used for lifecycle management (e.g., closing the server).

  12. Invoke the embed-oai Edge Function

    main

    The embed-oai Supabase Edge Function generates OpenAI embeddings for demo records and stores them in the database. It can be triggered via an HTTP POST request. The function expects a JSON payload containing either a demoId or a record object (typically used when triggered by database webhooks).

    Payload Requirements:

    • demoId: A string representing the ID of the demo to embed.
    • record: An object containing the database record, where record.id is used if demoId is not provided.
    • Note: You must provide either demoId or record.id, but not both. Providing both will result in an error.

    Environment Variables Required:

    • SUPABASE_DB_URL: Connection string for the PostgreSQL database.
    • OPENAI_API_KEY: Valid OpenAI API key for the text-embedding-3-small model.