Installation

Complete installation guide for the Produck SDK.

System Requirements

Node.js: 16.x or higher
Package Manager: npm, yarn, or pnpm
React: 18.0.0 or higher (for React bindings)
TypeScript: 5.0.0 or higher (optional, but recommended)

Package Installation

Install via your preferred package manager:

npm install @produck/sdk

Package Structure

The SDK is distributed as a single package with multiple entry points:

// Core SDK (framework-agnostic)
import { createProduck, ProduckSDK } from '@produck/sdk';
 
// React bindings
import { 
  ProduckProvider, 
  ProduckChat,
  useProduckAction,
  useProduckMessages 
} from '@produck/sdk/react';

TypeScript Support

The SDK includes built-in TypeScript definitions. No additional @types packages needed!

import type { 
  ProduckConfig,
  ActionPayload,
  ChatMessage 
} from '@produck/sdk';

TypeScript Configuration

Ensure your tsconfig.json includes:

tsconfig.json

{
  "compilerOptions": {
    "esModuleInterop": true,
    "skipLibCheck": true,
    "moduleResolution": "bundler"
  }
}

Framework-Specific Setup

Next.js (App Router)

app/layout.tsx

import { ProduckProvider } from '@produck/sdk/react';
 
export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <ProduckProvider config={{ sdkKey: process.env.NEXT_PUBLIC_SDK_KEY }}>
          {children}
        </ProduckProvider>
      </body>
    </html>
  );
}

Next.js (Pages Router)

pages/_app.tsx

import { ProduckProvider } from '@produck/sdk/react';
import type { AppProps } from 'next/app';
 
export default function App({ Component, pageProps }: AppProps) {
  return (
    <ProduckProvider config={{ sdkKey: process.env.NEXT_PUBLIC_SDK_KEY }}>
      <Component {...pageProps} />
    </ProduckProvider>
  );
}

Create React App

src/index.tsx

import React from 'react';
import ReactDOM from 'react-dom/client';
import { ProduckProvider } from '@produck/sdk/react';
import App from './App';
 
const root = ReactDOM.createRoot(document.getElementById('root')!);
root.render(
  <React.StrictMode>
    <ProduckProvider config={{ sdkKey: process.env.REACT_APP_SDK_KEY }}>
      <App />
    </ProduckProvider>
  </React.StrictMode>
);

Vite + React

src/main.tsx

import React from 'react';
import ReactDOM from 'react-dom/client';
import { ProduckProvider } from '@produck/sdk/react';
import App from './App';
 
ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <ProduckProvider config={{ sdkKey: import.meta.env.VITE_SDK_KEY }}>
      <App />
    </ProduckProvider>
  </React.StrictMode>,
);

Vanilla JavaScript

index.html

<!DOCTYPE html>
<html>
<head>
  <title>My App</title>
</head>
<body>
  <div id="app"></div>
  
  <script type="module">
    import { createProduck } from 'https://cdn.skypack.dev/@produck/sdk';
    
    const produck = createProduck({
      sdkKey: 'your-sdk-key'
    });
    
    await produck.init();
    
    produck.register('my-action', (payload) => {
      console.log('Action triggered!', payload);
    });
  </script>
</body>
</html>

Environment Variables

Recommended Setup

Store your SDK key in environment variables:

.env.local

# For Next.js
NEXT_PUBLIC_SDK_KEY=sdk_proj_your_key_here
 
# For Create React App
REACT_APP_SDK_KEY=sdk_proj_your_key_here
 
# For Vite
VITE_SDK_KEY=sdk_proj_your_key_here

Security Note

⚠️

SDK keys are meant to be public - they're used in frontend code. They only authenticate your project, not individual users. User authentication is handled through your organization's auth system.

Development vs Production

You can use different SDK keys for different environments:

.env.local

NEXT_PUBLIC_SDK_KEY=sdk_proj_dev_key_here

.env.production

NEXT_PUBLIC_SDK_KEY=sdk_proj_prod_key_here

Verify Installation

Test that everything is working:

components/TestSDK.tsx

'use client';
 
import { useProduckReady } from '@produck/sdk/react';
 
export function TestSDK() {
  const isReady = useProduckReady();
  
  return (
    <div>
      SDK Status: {isReady ? '✅ Ready' : '⏳ Initializing...'}
    </div>
  );
}

Bundle Size

The Produck SDK is optimized for production:

Core: ~8KB gzipped
React bindings: ~4KB gzipped
Total: ~12KB gzipped

Tree-shaking is supported - unused code is automatically removed.

Browser Support

The SDK supports all modern browsers:

Chrome 90+
Firefox 88+
Safari 14+
Edge 90+

CDN Usage (Not Recommended)

While possible, we recommend using npm for better version control:

<script type="module">
  import { createProduck } from 'https://cdn.jsdelivr.net/npm/@produck/sdk@latest/+esm';
</script>

Next Steps

Troubleshooting

Having issues? Check the Troubleshooting Guide or FAQ.

Getting Started Core Concepts