@gearbox-protocol/permissionless-ui

v2.0.1

Published

3 days ago

Internal UI components

Downloads

5,220

0High
0Medium
0Low

Permissionless UI

UI components for internal use - framework-agnostic React component library built with Tailwind CSS 4.

Installation

pnpm install @gearbox-protocol/permissionless-ui

For Next.js projects, also install Next.js:

pnpm install next

Setup

1. Configure Tailwind CSS

Create or update your tailwind.config.ts:

import type { Config } from "tailwindcss";
import { preset } from "@gearbox-protocol/permissionless-ui/preset";

const config: Config = {
  presets: [preset],
  content: [
    "./src/**/*.{js,ts,jsx,tsx,mdx}",
    "./node_modules/@gearbox-protocol/permissionless-ui/dist/**/*.js",
  ],
};

export default config;

2. Import Global Styles

In your main entry file:

import "@gearbox-protocol/permissionless-ui/globals.css";

3. Add Theme Provider (Optional)

For dark mode support:

import { ThemeProvider, ThemeScript } from "@gearbox-protocol/permissionless-ui";

// For Next.js App Router
export default function RootLayout({ children }) {
  return (
    <html suppressHydrationWarning>
      <head>
        {/* Prevents flash of white cards on page load */}
        <ThemeScript />
      </head>
      <body>
        <ThemeProvider defaultTheme="system">
          {children}
        </ThemeProvider>
      </body>
    </html>
  );
}

// For other frameworks (CRA, Vite, etc.)
function App() {
  return (
    <ThemeProvider defaultTheme="system">
      {/* Your app */}
    </ThemeProvider>
  );
}

Usage

Framework-agnostic (works everywhere)

import { Button, Input, Card } from '@gearbox-protocol/permissionless-ui';

function MyComponent() {
  return (
    <Card>
      <Input placeholder="Enter text" />
      <Button variant="default">Submit</Button>
    </Card>
  );
}

Next.js optimized

import { TokenIcon, BackButton, SIWEClientProvider } from '@gearbox-protocol/permissionless-ui/next';

// Uses Next.js Image, Link and useRouter
<TokenIcon symbol="ETH" size={48} />
<BackButton href="/dashboard" text="Back" />
<SIWEClientProvider apiRoutePrefix="/api/siwe">
  {children}
</SIWEClientProvider>

Custom components

import { TokenIcon, BackButton } from '@gearbox-protocol/permissionless-ui';
import MyImage from './MyImage';
import { Link } from 'react-router-dom';

<TokenIcon symbol="ETH" ImageComponent={MyImage} />
<BackButton href="/back" LinkComponent={Link} />

Dependencies

Required Peer Dependencies

These dependencies must be installed in your project:

pnpm install react react-dom @gearbox-protocol/sdk @tanstack/react-query viem wagmi connectkit reactochart

| Package | Version | Description | |---------|---------|-------------| | react | ^18 || ^19 | React library | | react-dom | ^18 || ^19 | React DOM | | @gearbox-protocol/sdk | * | Gearbox Protocol SDK | | @tanstack/react-query | ^5.64.1 | Data fetching and caching | | viem | ^2.0.0 | Ethereum library | | wagmi | ^2.0.0 | React hooks for Ethereum | | connectkit | ^1.8.0 | Wallet connection UI | | reactochart | ^6.1.1 | Charts library (used in Graph components) |

Optional Peer Dependencies

Install only if you use specific features:

| Package | Version | When to Install | |---------|---------|-----------------| | next | >=13 | Using @gearbox-protocol/permissionless-ui/next exports | | react-intl | ^6.0.0 || ^7.0.0 | Using internationalization features | | react-router-dom | ^6.0.0 || ^7.0.0 | Using router-based navigation (non-Next.js) | | sonner | ^2.0.0 | Using toast notifications |

Installation Examples

Minimal setup (basic components only):

pnpm install @gearbox-protocol/permissionless-ui react react-dom

Full Web3 setup:

pnpm install @gearbox-protocol/permissionless-ui \
  react react-dom \
  @gearbox-protocol/sdk @tanstack/react-query \
  viem wagmi connectkit reactochart

With Next.js:

pnpm install @gearbox-protocol/permissionless-ui \
  react react-dom next \
  @gearbox-protocol/sdk @tanstack/react-query \
  viem wagmi connectkit reactochart

With routing (React Router):

pnpm install @gearbox-protocol/permissionless-ui \
  react react-dom react-router-dom \
  @gearbox-protocol/sdk @tanstack/react-query \
  viem wagmi connectkit reactochart

With internationalization:

pnpm install @gearbox-protocol/permissionless-ui react-intl

Package Exports

The library provides several entry points:

| Export | Description | |--------|-------------| | @gearbox-protocol/permissionless-ui | Main entry - all framework-agnostic components | | @gearbox-protocol/permissionless-ui/next | Next.js optimized components (Image, Link, Router) | | @gearbox-protocol/permissionless-ui/preset | Tailwind CSS preset | | @gearbox-protocol/permissionless-ui/tailwind | Tailwind CSS config | | @gearbox-protocol/permissionless-ui/globals.css | Global CSS styles | | @gearbox-protocol/permissionless-ui/grid-safelist.css | Grid safelist CSS |

Troubleshooting

Module not found errors

If you see errors like Cannot find module '@gearbox-protocol/sdk', install the missing peer dependency:

pnpm install @gearbox-protocol/sdk

TypeScript errors

Install type definitions for React:

pnpm install -D @types/react @types/react-dom

Tailwind styles not working

Make sure you've added the library's dist folder to your Tailwind content config:

content: [
  "./node_modules/@gearbox-protocol/permissionless-ui/dist/**/*.js",
]

Import the global styles in your entry file:

import "@gearbox-protocol/permissionless-ui/globals.css";

Next.js specific components not working

Make sure you've installed Next.js and are importing from the correct path:

// ✅ Correct
import { TokenIcon } from '@gearbox-protocol/permissionless-ui/next';

// ❌ Wrong - these won't have Next.js optimizations
import { TokenIcon } from '@gearbox-protocol/permissionless-ui';

Important information for contributors

As a contributor to the Gearbox Protocol GitHub repository, your pull requests indicate acceptance of our Gearbox Contribution Agreement. This agreement outlines that you assign the Intellectual Property Rights of your contributions to the Gearbox Foundation. This helps safeguard the Gearbox protocol and ensure the accumulation of its intellectual property. Contributions become part of the repository and may be used for various purposes, including commercial. As recognition for your expertise and work, you receive the opportunity to participate in the protocol's development and the potential to see your work integrated within it. The full Gearbox Contribution Agreement is accessible within the repository for comprehensive understanding. [Let's innovate together!]