npm package: @gearbox-protocol/permissionless-ui
Description: Internal UI components
Latest version: 2.0.1
Deprecated: Package no longer supported. Contact Support at https://www.npmjs.com/support for more info.

# Permissionless UI

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

## Installation

```bash
pnpm install @gearbox-protocol/permissionless-ui
```

For Next.js projects, also install Next.js:
```bash
pnpm install next
```

## Setup

### 1. Configure Tailwind CSS

Create or update your `tailwind.config.ts`:

```typescript
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:

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

### 3. Add Theme Provider (Optional)

For dark mode support:

```tsx
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)

```tsx
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

```tsx
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

```tsx
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:

```bash
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):**
```bash
pnpm install @gearbox-protocol/permissionless-ui react react-dom
```

**Full Web3 setup:**
```bash
pnpm install @gearbox-protocol/permissionless-ui \
  react react-dom \
  @gearbox-protocol/sdk @tanstack/react-query \
  viem wagmi connectkit reactochart
```

**With Next.js:**
```bash
pnpm install @gearbox-protocol/permissionless-ui \
  react react-dom next \
  @gearbox-protocol/sdk @tanstack/react-query \
  viem wagmi connectkit reactochart
```

**With routing (React Router):**
```bash
pnpm install @gearbox-protocol/permissionless-ui \
  react react-dom react-router-dom \
  @gearbox-protocol/sdk @tanstack/react-query \
  viem wagmi connectkit reactochart
```

**With internationalization:**
```bash
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:

```bash
pnpm install @gearbox-protocol/sdk
```

### TypeScript errors

Install type definitions for React:

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

### Tailwind styles not working

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

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

2. Import the global styles in your entry file:

```typescript
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:

```typescript
// ✅ 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](/ContributionAgreement) for comprehensive understanding. [Let's innovate together!]