Installation

This guide will help you install and set up the Vaultys Peer SDK for building P2P applications with decentralized identities.

Prerequisites

Before you begin, ensure you have:

• Node.js version 16.0.0 or higher
• npm (v7+) or yarn (v1.22+) or pnpm (v6+)
• A modern web browser (Chrome 86+, Firefox 78+, Safari 14+, Edge 86+)
• TypeScript 4.5+ (optional, for TypeScript projects)

Quick Install

# Core packages for P2P functionality
npm install @vaultys/peer-sdk @vaultys/id

# Optional: For collaborative features
npm install yjs y-indexeddb

Package Overview

Core Packages

@vaultys/id

Handles decentralized identity (DID) creation and management:

• Software-based key generation
• WebAuthn/Passkey support
• Identity persistence and recovery

@vaultys/peer-sdk

Provides P2P communication infrastructure:

• Peer-to-peer messaging
• File sharing
• Contact management
• Collaborative spaces

Optional Dependencies

# For Node.js applications (WebRTC support)
npm install @roamhq/wrtc

# For collaborative text editing
npm install quill quill-cursors y-quill

# For enhanced storage in browsers
npm install idb

Platform Setup

Browser Applications

Modern browsers have everything you need built-in. Simply import and use:

import { setupVaultysPeerSDK, BrowserStorageProvider } from '@vaultys/peer-sdk';
import { VaultysId } from '@vaultys/id';

// Ready to go!
const vaultysId = await VaultysId.generatePerson();
const peer = setupVaultysPeerSDK({
  vaultysId,
  storageProvider: new BrowserStorageProvider()
});

React Applications

# Create React App
npx create-react-app my-p2p-app
cd my-p2p-app
npm install @vaultys/peer-sdk @vaultys/id

# Or with Vite (recommended for better performance)
npm create vite@latest my-p2p-app -- --template react
cd my-p2p-app
npm install
npm install @vaultys/peer-sdk @vaultys/id

Example React setup:

// App.jsx
import { useEffect, useState } from 'react';
import { setupVaultysPeerSDK, BrowserStorageProvider } from '@vaultys/peer-sdk';
import { VaultysId } from '@vaultys/id';

function App() {
  const [peer, setPeer] = useState(null);
  const [identity, setIdentity] = useState(null);

  useEffect(() => {
    const initPeer = async () => {
      // Load or create identity
      let vaultysId;
      const stored = localStorage.getItem('vaultysIdentity');
      
      if (stored) {
        const { secret } = JSON.parse(stored);
        vaultysId = VaultysId.fromSecret(secret);
      } else {
        vaultysId = await VaultysId.generatePerson();
        localStorage.setItem('vaultysIdentity', JSON.stringify({
          did: vaultysId.did,
          secret: vaultysId.getSecret()
        }));
      }

      setIdentity(vaultysId);

      // Initialize peer service
      const peerService = setupVaultysPeerSDK({
        vaultysId,
        storageProvider: new BrowserStorageProvider()
      });

      await peerService.initialize();
      setPeer(peerService);
    };

    initPeer();
  }, []);

  return (
    <div>
      {identity && <p>My DID: {identity.did}</p>}
      {peer && <p>Connected to P2P network ✅</p>}
    </div>
  );
}

export default App;

Next.js Applications

npx create-next-app@latest my-p2p-app
cd my-p2p-app
npm install @vaultys/peer-sdk @vaultys/id

For Next.js, use dynamic imports for client-side only code:

// components/P2PChat.js
import dynamic from 'next/dynamic';

const P2PChatComponent = dynamic(
  () => import('./P2PChatClient'),
  { ssr: false }
);

export default function P2PChat() {
  return <P2PChatComponent />;
}

Node.js Applications

For server-side or CLI applications:

npm install @vaultys/peer-sdk @vaultys/id @roamhq/wrtc

// setup.js
import { setupVaultysPeerSDK, NodeFSStorageProvider, setupNodeWebRTC } from '@vaultys/peer-sdk';
import { VaultysId } from '@vaultys/id';
import wrtc from '@roamhq/wrtc';

// Configure WebRTC for Node.js
setupNodeWebRTC(wrtc);

async function createNodePeer() {
  const vaultysId = await VaultysId.generateMachine();
  
  const peer = setupVaultysPeerSDK({
    vaultysId,
    storageProvider: new NodeFSStorageProvider('./data')
  });
  
  await peer.initialize();
  return peer;
}

TypeScript Configuration

For TypeScript projects, add to your tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "lib": ["ES2020", "DOM", "DOM.Iterable"],
    "moduleResolution": "node",
    "esModuleInterop": true,
    "allowSyntheticDefaultImports": true,
    "strict": true,
    "skipLibCheck": true,
    "resolveJsonModule": true,
    "declaration": true,
    "outDir": "./dist",
    "rootDir": "./src"
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

Build Tools Configuration

Vite

// vite.config.js
import { defineConfig } from 'vite';

export default defineConfig({
  optimizeDeps: {
    include: ['@vaultys/peer-sdk', '@vaultys/id']
  },
  build: {
    target: 'es2020'
  }
});

Webpack 5

// webpack.config.js
module.exports = {
  resolve: {
    fallback: {
      "crypto": false,
      "stream": false,
      "buffer": false
    },
    extensions: ['.js', '.jsx', '.ts', '.tsx']
  },
  module: {
    rules: [
      {
        test: /\.(js|jsx|ts|tsx)$/,
        exclude: /node_modules/,
        use: {
          loader: 'babel-loader'
        }
      }
    ]
  }
};

Rollup

// rollup.config.js
import resolve from '@rollup/plugin-node-resolve';
import commonjs from '@rollup/plugin-commonjs';

export default {
  input: 'src/index.js',
  output: {
    file: 'dist/bundle.js',
    format: 'esm'
  },
  plugins: [
    resolve({
      browser: true,
      preferBuiltins: false
    }),
    commonjs()
  ]
};

Testing Installation

Create a test file to verify everything is working:

// test-setup.js
import { setupVaultysPeerSDK, BrowserStorageProvider } from '@vaultys/peer-sdk';
import { VaultysId } from '@vaultys/id';

async function testSetup() {
  try {
    // Test identity creation
    console.log('Creating identity...');
    const vaultysId = await VaultysId.generatePerson();
    console.log('✅ Identity created:', vaultysId.did);

    // Test peer service setup
    console.log('Setting up peer service...');
    const peer = setupVaultysPeerSDK({
      vaultysId,
      storageProvider: new BrowserStorageProvider(),
      relay: {
        host: 'peerjs.92k.de',
        secure: true
      }
    });

    // Test initialization
    console.log('Initializing connection...');
    await peer.initialize();
    console.log('✅ Connected to P2P network');

    // Test adding a contact
    console.log('Testing contact management...');
    const testContact = await peer.addContact('did:vaultys:test123', {
      nickname: 'Test Contact'
    });
    console.log('✅ Contact added:', testContact);

    console.log('\n🎉 All tests passed! Setup is working correctly.');
    
    // Clean up
    await peer.disconnect();
    
  } catch (error) {
    console.error('❌ Test failed:', error);
  }
}

testSetup();

Run the test:

# For browser - create an HTML file:
cat > test.html << 'EOF'
<!DOCTYPE html>
<html>
<head><title>Test Setup</title></head>
<body>
  <h1>Check console for test results</h1>
  <script type="module" src="test-setup.js"></script>
</body>
</html>
EOF

# Serve it locally:
npx serve .

# For Node.js:
node test-setup.js

CDN Usage

For quick prototypes or demos, you can use the SDK via CDN:

<!DOCTYPE html>
<html>
<head>
  <title>Vaultys P2P Demo</title>
</head>
<body>
  <div id="app">
    <h1>P2P Demo</h1>
    <div id="status">Initializing...</div>
    <div id="did"></div>
  </div>

  <script type="module">
    import { setupVaultysPeerSDK, BrowserStorageProvider } from 'https://cdn.jsdelivr.net/npm/@vaultys/peer-sdk@latest/+esm';
    import { VaultysId } from 'https://cdn.jsdelivr.net/npm/@vaultys/id@latest/+esm';

    async function init() {
      const vaultysId = await VaultysId.generatePerson();
      document.getElementById('did').textContent = `My DID: ${vaultysId.did}`;

      const peer = setupVaultysPeerSDK({
        vaultysId,
        storageProvider: new BrowserStorageProvider()
      });

      peer.on('relay-connected', () => {
        document.getElementById('status').textContent = 'Connected ✅';
      });

      await peer.initialize();
    }

    init().catch(console.error);
  </script>
</body>
</html>

Troubleshooting

Common Issues and Solutions

Module not found errors

# Clear npm cache and reinstall
npm cache clean --force
rm -rf node_modules package-lock.json
npm install

TypeScript type errors

# Ensure types are installed
npm install --save-dev @types/node
# Restart TypeScript server in your IDE

WebRTC not available in Node.js

# Install and initialize wrtc
npm install @roamhq/wrtc

import wrtc from '@roamhq/wrtc';
import { setupNodeWebRTC } from '@vaultys/peer-sdk';
setupNodeWebRTC(wrtc);

CORS errors in browser

# Use a proper web server, not file:// protocol
npx serve .
# or
python3 -m http.server 8000
# or
php -S localhost:8000

Browser storage quota exceeded

// Check available storage
if (navigator.storage && navigator.storage.estimate) {
  const estimate = await navigator.storage.estimate();
  console.log(`Using ${estimate.usage} out of ${estimate.quota} bytes`);
}

Environment Variables

For production deployments, you can configure the SDK using environment variables:

# .env
VITE_RELAY_HOST=your-relay-server.com
VITE_RELAY_PORT=443
VITE_RELAY_SECURE=true
VITE_ICE_SERVERS=stun:stun.l.google.com:19302,turn:turn.example.com

// Use in your app
const peer = setupVaultysPeerSDK({
  vaultysId,
  relay: {
    host: import.meta.env.VITE_RELAY_HOST || 'peerjs.92k.de',
    port: import.meta.env.VITE_RELAY_PORT || 443,
    secure: import.meta.env.VITE_RELAY_SECURE !== 'false'
  }
});

Next Steps

Now that you have everything installed:

1. Quick Start: Jump into building your first P2P app
2. Try the Playground: Test features at /playground
3. Examples: Check out working examples
4. API Reference: Deep dive into the API documentation

Version Matrix

Vaultys SDK	Node.js	Browser Support	React	Next.js	Features
1.0.x	16+	Chrome 86+, Firefox 78+, Safari 14+	17+	12+	Full P2P, Spaces, WebAuthn
0.9.x	14+	Chrome 80+, Firefox 72+, Safari 13+	16.8+	11+	Basic P2P, Messages

Getting Help

• 📖 Documentation
• 🎮 Interactive Playground
• 💬 Discord Community
• 🐛 Report Issues
• ✉️ Email Support