npm package: @nicksdigital/next-soulstream
Description: SoulStream Protocol integration for Next.js applications
Author: Nick
Latest version: 0.1.1

# next-soulstream

A TypeScript-based Next.js plugin for integrating the SoulStream Protocol into your Next.js 15+ applications, with cross-chain support.

## Features

- Full TypeScript support
- Node.js 20+ compatibility
- React 18+ and Next.js 15+ integration
- Cross-chain support (Ethereum, Polygon, etc.)
- Modern ESM and CommonJS support
- Strongly typed components and hooks

## Installation

```bash
npm install next-soulstream
# or
yarn add next-soulstream
# or
pnpm add next-soulstream
```

## Requirements

- Node.js 20 or higher
- Next.js 15 or higher
- React 18 or higher

## Setup

### 1. Update your Next.js config

Add the plugin to your `next.config.js` or `next.config.mjs`:

```typescript
import withSoulStream from 'next-soulstream';
// Or for CommonJS
// const { default: withSoulStream } = require('next-soulstream');

/** @type {import('next').NextConfig} */
const nextConfig = {
  // Your existing Next.js config
};

// Basic usage
export default withSoulStream(nextConfig);

// With options
export default withSoulStream(nextConfig, {
  // Use testnet configuration (Goerli and Mumbai)
  testMode: process.env.NODE_ENV === 'production' ? false : true,
  
  // Other options
  devMode: process.env.NODE_ENV !== 'production',
});
```

### 2. Configure environment variables

The plugin requires the following environment variables:

```env
# Chain A (Ethereum)
NEXT_PUBLIC_CHAIN_A_ID=31337
NEXT_PUBLIC_CHAIN_A_RPC_URL=http://localhost:8545
NEXT_PUBLIC_CHAIN_A_REGISTRY_ADDRESS=0x5FbDB2315678afecb367f032d93F642f64180aa3
NEXT_PUBLIC_CHAIN_A_BRIDGE_ADAPTER_ADDRESS=0xe7f1725E7734CE288F8367e1Bb143E90bb3F0512

# Chain B (Polygon)
NEXT_PUBLIC_CHAIN_B_ID=31338
NEXT_PUBLIC_CHAIN_B_RPC_URL=http://localhost:8546
NEXT_PUBLIC_CHAIN_B_REGISTRY_ADDRESS=0x5FbDB2315678afecb367f032d93F642f64180aa3
NEXT_PUBLIC_CHAIN_B_BRIDGE_ADAPTER_ADDRESS=0xe7f1725E7734CE288F8367e1Bb143E90bb3F0512

# For private key (optional, only needed for some operations)
PRIVATE_KEY=your_private_key_here
```

For convenience, the plugin includes default values for local development. In production, you should provide real values.

### 3. Set up the SoulStream Provider

In your application, wrap your components with the SoulStream provider:

```tsx
// app/layout.tsx or pages/_app.tsx
import { SoulStreamProvider } from 'next-soulstream';
import type { SoulStreamConfig } from 'next-soulstream';

export default function RootLayout({ children }) {
  const soulStreamConfig: SoulStreamConfig = {
    rpcUrl: process.env.NEXT_PUBLIC_RPC_URL || '',
    contractAddress: process.env.NEXT_PUBLIC_SOULSTREAM_CONTRACT || '',
    contractABI: [...], // Your contract ABI
    // Chain configurations will be automatically loaded from environment variables
  };

  return (
    <html lang="en">
      <body>
        <SoulStreamProvider config={soulStreamConfig}>
          {children}
        </SoulStreamProvider>
      </body>
    </html>
  );
}
```

## Usage

### Import Components

```tsx
import { 
  ReputationComponent, 
  RewardsComponent,
  ChainSwitcher
} from 'next-soulstream';
```

### Display Reputation

```tsx
<ReputationComponent 
  walletAddress="0x123..." 
  showDetails={true} 
/>
```

### Display Rewards

```tsx
<RewardsComponent 
  walletAddress="0x123..." 
  showClaimed={true} 
  showUnclaimed={true} 
/>
```

### Switch Between Chains

```tsx
<ChainSwitcher 
  onSwitch={(chainId, success) => {
    console.log(`Switched to chain ${chainId}: ${success ? 'Success' : 'Failed'}`);
  }}
  className="my-custom-class"
/>
```

### Use the SoulStream Context Hook

```tsx
import { useSoulStream } from 'next-soulstream';

function MyComponent() {
  const { 
    getReputationScore, 
    chains, 
    currentChainId, 
    switchChain 
  } = useSoulStream();
  
  const handleSwitchChain = async () => {
    // Switch to Chain B (Polygon)
    if (chains.chainB) {
      const success = await switchChain(chains.chainB.chainId);
      if (success) {
        console.log('Successfully switched to Polygon');
      }
    }
  };
  
  return (
    <div>
      <p>Current Network: {currentChainId === chains.chainA?.chainId ? 'Ethereum' : 'Polygon'}</p>
      <button onClick={handleSwitchChain}>
        Switch to Polygon
      </button>
    </div>
  );
}
```

## Cross-Chain Development

The SoulStream plugin supports cross-chain functionality out of the box. You can:

1. **Switch between networks** using the `ChainSwitcher` component or the `switchChain` function
2. **Access chain-specific data** through the context
3. **Use consistent interfaces** across different chains

For local development, the plugin defaults to using Hardhat-compatible localhost configurations (ports 8545 and 8546).

## Type Support

All components and functions are fully typed:

```tsx
import type { 
  ReputationData, 
  RewardsData, 
  SoulStreamConfig,
  ChainConfig
} from 'next-soulstream';

// You can use these types in your application
const myChainConfig: ChainConfig = {
  chainId: '1',
  rpcUrl: 'https://mainnet.infura.io/v3/YOUR_INFURA_KEY',
  registryAddress: '0x...',
  bridgeAdapterAddress: '0x...'
};
```

## Development

If you want to build the plugin locally:

```bash
git clone https://github.com/nick/next-soulstream.git
cd next-soulstream
npm install
npm run build
```

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## License

MIT