hunt-mint-swap/README.md

A React component library for swapping MINT / HUNT buildings

<p align="center">
  <img src="https://mint.club/logo.png" alt="Mint Club" width="80" />
</p>

<h1 align="center">hunt-mint-swap</h1>

<p align="center">
  React component library for token swapping and Hunt Building mint flows — wagmi + viem, Mint Club bonding curve + Uniswap routing in one widget.
</p>

<p align="center">
  <a href="https://www.npmjs.com/package/hunt-mint-swap"><img src="https://img.shields.io/npm/v/hunt-mint-swap.svg?style=flat-square&label=npm" alt="npm" /></a>
  <a href="https://www.npmjs.com/package/hunt-mint-swap"><img src="https://img.shields.io/npm/dm/hunt-mint-swap.svg?style=flat-square&label=downloads" alt="downloads" /></a>
  <a href="https://packagephobia.com/result?p=hunt-mint-swap"><img src="https://packagephobia.com/badge?p=hunt-mint-swap" alt="install size" /></a>
  <a href="https://github.com/Steemhunt/hunt-mint-swap"><img src="https://img.shields.io/github/stars/Steemhunt/hunt-mint-swap?style=flat-square&logo=github" alt="GitHub" /></a>
  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square" alt="MIT" /></a>
</p>

---

## Features

- 🔄 MintSwap Component: Seamless token swapping interface
- 🏗️ HuntBuildingsModal: Building minting and management interface
- 🌐 Wagmi Integration: Robust wallet connection
- ⚡ Viem/Wagmi Support: Robust Web3 interactions
- 🎨 Modern UI with Tailwind CSS

## Installation

```bash
npm install hunt-mint-swap
# or
yarn add hunt-mint-swap
# or
pnpm add hunt-mint-swap
```

## Prerequisites

This package requires the following peer dependencies:

```json
{
  "react": ">=19.1.0",
  "react-dom": ">=19.1.0",
  "viem": ">=2.29.2",
  "wagmi": ">=2.15.3"
}
```

## Setup

### 1. Import Styles

The components use Tailwind CSS for styling. You **must** import the component styles in your application:

```tsx
// In your app's entry point (e.g., App.tsx or index.tsx)
import "hunt-mint-swap/style.css";
```

### 2. Configure Tailwind CSS

If you're using Tailwind CSS in your project, add the component paths to your `tailwind.config.js`:

```js
/** @type {import('tailwindcss').Config} */
module.exports = {
  content: [
    // ... your other content paths
    "./node_modules/hunt-mint-swap/**/*.{js,jsx,ts,tsx}",
  ],
  theme: {
    extend: {},
  },
  plugins: [],
};
```

### 3. Setup Required Providers

The library requires specific providers to be set up in your app. Create a wrapper component like this:

```tsx
// App.tsx or your root component
import { WagmiProvider, createConfig, http } from "wagmi";
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { mainnet, base } from "viem/chains";
import { HuntMintSwapProvider } from "hunt-mint-swap";

// Get your project ID from WalletConnect Cloud
const projectId = "YOUR_WALLET_CONNECT_PROJECT_ID";

// Create wagmi config
const config = createConfig({
  chains: [mainnet, base],
  transports: {
    [mainnet.id]: http(),
    [base.id]: http(),
  },
});

const queryClient = new QueryClient();

function App() {
  return (
    <WagmiProvider config={config}>
      <QueryClientProvider client={queryClient}>
        <HuntMintSwapProvider>{/* Your app content */}</HuntMintSwapProvider>
      </QueryClientProvider>
    </WagmiProvider>
  );
}

export default App;
```

### 4. Environment Variables

Make sure to set up the following environment variables in your `.env` file:

```env
VITE_DECENT_API_KEY=your_decent_api_key
```

## Usage

### MintSwap Component

```tsx
import { MintSwap } from "hunt-mint-swap";

function App() {
  const [isOpen, setIsOpen] = useState(false);

  return (
    <MintSwap
      isOpen={isOpen}
      onClose={() => setIsOpen(false)}
      className="custom-class"
    />
  );
}
```

### HuntBuildingsModal Component

```tsx
import { HuntBuildingsModal } from "hunt-mint-swap";

function App() {
  const [isOpen, setIsOpen] = useState(false);

  return (
    <HuntBuildingsModal
      isOpen={isOpen}
      onClose={() => setIsOpen(false)}
      className="custom-class"
    />
  );
}
```

## Component Props

### MintSwap Props

| Prop      | Type       | Description                                |
| --------- | ---------- | ------------------------------------------ |
| isOpen    | boolean    | Controls the visibility of the swap modal  |
| onClose   | () => void | Callback function when modal is closed     |
| className | string?    | Optional CSS class for custom on container |

### HuntBuildingsModal Props

| Prop      | Type       | Description                                    |
| --------- | ---------- | ---------------------------------------------- |
| isOpen    | boolean    | Controls the visibility of the buildings modal |
| onClose   | () => void | Callback function when modal is closed         |
| className | string?    | Optional CSS class for custom on container     |

## Troubleshooting

### Common Issues

1. **White Screen**: If you see a white screen, make sure you have:

   - Imported the CSS file
   - Set up all required providers
   - Set the WalletConnect project ID
   - Set the DECENT API key in your environment variables

2. **Provider Errors**: Ensure your providers are in the correct order:

   ```tsx
   WagmiProvider -> QueryClientProvider -> HuntMintSwapProvider
   ```

3. **Style Issues**: If styles are not loading:
   - Check that you've imported the CSS file
   - Verify your Tailwind configuration includes the package path
   - Make sure PostCSS is properly configured in your build setup

## Contributing

We welcome contributions! Please see our contributing guide for details.

## License

MIT

## Support

For support, please open an issue in the GitHub repository: https://github.com/Steemhunt/hunt-mint-swap/issues