React Bits Pro Integration

Architecture overview

React Bits Pro uses the shadcn registry protocol to distribute components. There are two authenticated registries:

Components are installed directly into the user's codebase (not as npm packages). They become local source files the user owns and can modify.

Component variants

Every component (from @reactbits-starter) has TWO variants:

• -tw (Tailwind) — uses Tailwind CSS utility classes via cn() helper. Preferred for Tailwind projects.
• -css (CSS) — uses a co-located .css file with vanilla CSS. Use when the project does not use Tailwind.

Every block (from @reactbits-pro) has only ONE version — Tailwind-based, no suffix needed.

File installation paths

When installed, files land at:

• Components: components/react-bits/{component-name}.tsx (and .css for CSS variant)
• Blocks: components/blocks/{block-name}.tsx

Step 1: Verify prerequisites

Before installing anything, confirm the user's project has:

1. A components.json file in the project root (shadcn config). If missing, run:

   npx shadcn@latest init
   

2. The cn utility at lib/utils.ts:

   import { clsx, type ClassValue } from "clsx"
   import { twMerge } from "tailwind-merge"
   
   export function cn(...inputs: ClassValue[]) {
     return twMerge(clsx(inputs))
   }
   

   If missing, install dependencies: npm install clsx tailwind-merge

3. A valid license key. The user must have purchased a React Bits Pro license. Ask the user for their license key if they haven't set it up yet.

Step 2: Configure the license key

The license key must be in a .env.local file in the project root:

REACTBITS_LICENSE_KEY=<the-users-license-key>

CRITICAL: Never commit .env.local to version control. Ensure .gitignore includes it.

Step 3: Configure components.json

Add the React Bits Pro registries to the registries field in components.json. If the registries key does not exist, create it.

{
  "registries": {
    "@reactbits-starter": {
      "url": "https://pro.reactbits.dev/api/r/starter/{name}.json",
      "headers": {
        "Authorization": "Bearer ${REACTBITS_LICENSE_KEY}"
      }
    },
    "@reactbits-pro": {
      "url": "https://pro.reactbits.dev/api/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${REACTBITS_LICENSE_KEY}"
      }
    }
  }
}

Do NOT overwrite existing components.json fields ($schema, style, tailwind, aliases, etc.). Only add or merge the registries object.

Step 4: Install components

Installing a component (from @reactbits-starter)

# Tailwind variant (recommended for Tailwind projects)
npx shadcn@latest add @reactbits-starter/{component-slug}-tw

# CSS variant (for non-Tailwind projects)
npx shadcn@latest add @reactbits-starter/{component-slug}-css

Installing a block (from @reactbits-pro)

npx shadcn@latest add @reactbits-pro/{block-slug}

Installing multiple at once

npx shadcn@latest add @reactbits-starter/silk-waves-tw @reactbits-starter/animated-list-tw @reactbits-pro/hero-1

Step 5: Use the installed component

After installation, import and use the component:

// Component example
import SilkWaves from "@/components/react-bits/silk-waves";

export default function MyPage() {
  return (
    <div className="h-screen w-full">
      <SilkWaves
        speed={1}
        scale={2}
        colors={["#0d1326", "#162a52", "#1e407e", "#2657aa", "#2e6ed5", "#3785ff", "#5092ff", "#69a0ff"]}
      />
    </div>
  );
}

// Block example
import { Hero1 } from "@/components/blocks/hero-1";

export default function LandingPage() {
  return (
    <main>
      <Hero1 />
    </main>
  );
}

Import patterns

• Components use default exports: import ComponentName from "@/components/react-bits/{slug}"
• Blocks use named exports matching PascalCase of slug: import { Hero1 } from "@/components/blocks/hero-1"
  • The exported function name is the PascalCase version: hero-1 → Hero1, pricing-3 → Pricing3, navigation-2 → Navigation2
• All components and blocks include the "use client" directive — they are client components

Complete component catalog

Components (@reactbits-starter) — 88 components

All components are starter tier (accessible with any paid license).

Text & Typography animations

Cursor effects

Cards & interactive elements

Backgrounds & visual effects

Galleries, carousels & layout

Other

Blocks (@reactbits-pro) — 120+ page sections

All blocks are pro tier (requires Pro or Ultimate license). Blocks are Tailwind-only.

Common dependency requirements

Many components use specialized libraries. When you install via the shadcn CLI, dependencies are automatically resolved. However, be aware of these key dependencies so you can help the user troubleshoot:

Important: "use client" directive

ALL React Bits Pro components and blocks include "use client" at the top. They are client components. If you are using them in a Server Component page in Next.js App Router, simply import them — Next.js handles the client boundary automatically. Do NOT try to remove the "use client" directive.

Building a landing page with blocks

A common use case is composing a full landing page from blocks. Here is the recommended approach:

1. Install the blocks you need

npx shadcn@latest add @reactbits-pro/navigation-1 @reactbits-pro/hero-1 @reactbits-pro/features-1 @reactbits-pro/social-proof-1 @reactbits-pro/pricing-1 @reactbits-pro/faq-1 @reactbits-pro/cta-1 @reactbits-pro/footer-1

2. Compose them in a page

import { Navigation1 } from "@/components/blocks/navigation-1";
import { Hero1 } from "@/components/blocks/hero-1";
import { Features1 } from "@/components/blocks/features-1";
import { SocialProof1 } from "@/components/blocks/social-proof-1";
import { Pricing1 } from "@/components/blocks/pricing-1";
import { Faq1 } from "@/components/blocks/faq-1";
import { Cta1 } from "@/components/blocks/cta-1";
import { Footer1 } from "@/components/blocks/footer-1";

export default function LandingPage() {
  return (
    <>
      <Navigation1 />
      <Hero1 />
      <Features1 />
      <SocialProof1 />
      <Pricing1 />
      <Faq1 />
      <Cta1 />
      <Footer1 />
    </>
  );
}

3. Customize content

Blocks are installed as local source files. Edit them directly to:

• Replace placeholder text, images, and links with real content
• Adjust colors to match the brand
• Modify layout or spacing
• Add or remove sections within the block
• Wire up form submissions, button clicks, and navigation links

Combining components with blocks

You can use standalone components inside blocks or alongside them:

import SilkWaves from "@/components/react-bits/silk-waves";
import { Hero1 } from "@/components/blocks/hero-1";

export default function LandingPage() {
  return (
    <>
      {/* Animated background behind the hero */}
      <div className="relative">
        <div className="absolute inset-0 -z-10">
          <SilkWaves speed={0.5} opacity={0.3} />
        </div>
        <Hero1 />
      </div>
    </>
  );
}

Customizing components

Since components are local source files, you can customize them freely:

Props customization (no code changes needed)

Most components accept extensive props. For example, SilkWaves:

<SilkWaves
  speed={1.5}
  scale={3}
  distortion={0.8}
  curve={1.2}
  contrast={1}
  colors={["#1a0533", "#2d1b69", "#4a2c8a", "#6b3fa0", "#8b52b8", "#ab65d0", "#cb78e8", "#eb8bff"]}
  rotation={45}
  brightness={1.2}
  opacity={0.9}
  complexity={1.5}
  frequency={1.2}
  className="absolute inset-0"
/>

Source code modification

For deeper changes, edit the installed .tsx file directly. Common modifications:

• Changing animation parameters or timing
• Adjusting responsive breakpoints
• Adding new props
• Modifying color schemes
• Integrating with state management
• Connecting to APIs or databases

Dark mode support

All blocks and most components support dark mode via Tailwind's dark: variant. They use the standard dark class strategy. Ensure your app has a theme provider set up:

// layout.tsx
import { ThemeProvider } from "next-themes";

export default function RootLayout({ children }) {
  return (
    <html lang="en" suppressHydrationWarning>
      <body>
        <ThemeProvider attribute="class" defaultTheme="system" enableSystem>
          {children}
        </ThemeProvider>
      </body>
    </html>
  );
}

Troubleshooting

"Unknown registry @reactbits-starter"

The registries block is missing from components.json. Add it per Step 3 above.

"Unauthorized - License key required"

The REACTBITS_LICENSE_KEY environment variable is not set. Add it to .env.local.

"Forbidden - Insufficient tier"

The user's license tier doesn't include access to the requested content. Starter licenses cannot access @reactbits-pro blocks — a Pro or Ultimate license is required.

Component not found

• For components: ensure you're using the -tw or -css suffix (e.g., silk-waves-tw, not silk-waves)
• For blocks: do NOT add a suffix (e.g., hero-1, not hero-1-tw)

Missing cn function

Install the utility: npm install clsx tailwind-merge, then create lib/utils.ts with the cn function shown in Step 1.

WebGL/Three.js components show blank

• Ensure three is installed: npm install three
• These components require a browser with WebGL support
• The component's container must have explicit dimensions (width/height)
• For SSR frameworks, the "use client" directive handles client-only rendering

GSAP scroll animations not working

• Ensure gsap and @gsap/react are installed
• ScrollTrigger is registered automatically in component code
• The scroll container must be the default document scroll (not a custom scroll container) unless configured

Blocks look unstyled

• Ensure Tailwind CSS is properly configured
• Blocks use Tailwind v4 syntax — if using v3, minor class adjustments may be needed
• Check that globals.css imports Tailwind: @import "tailwindcss"

Best practices

1. Choose one variant and be consistent — pick either -tw or -css for all components in a project
2. Always use the Tailwind variant (-tw) if the project uses Tailwind CSS — it integrates better and is smaller
3. Give WebGL components explicit dimensions — wrap them in a container with set width/height
4. Lazy-load heavy components — use next/dynamic for Three.js-based components if not above the fold:

   import dynamic from "next/dynamic";
   const SilkWaves = dynamic(() => import("@/components/react-bits/silk-waves"), { ssr: false });
   

5. Keep license keys secure — never hardcode them; always use environment variables
6. Customize blocks by editing source — blocks are meant to be starting points, not rigid templates
7. Preview before installing — use npx shadcn@latest view @reactbits-starter/silk-waves-tw to inspect a component before adding it
8. Install this skill into projects — run npx shadcn@latest add @reactbits-starter/skill to drop this SKILL.md into the project root so agents always have it available locally