SaraCRM Web SDK

An embeddable React chat SDK that integrates seamlessly with Next.js 14+ App Router, Turbopack, and any React application.

Features

• Works with Next.js 14+ App Router and Turbopack
• Safe SSR (Server-Side Rendering) support
• Client-side only rendering with 'use client' directive
• ESM and CJS builds included
• Proper CSS bundling and injection
• Safe localStorage usage with SSR guards
• React 18 & 19 compatible
• No configuration needed in consuming apps

Installation

npm install saracrm-web-sdk
# or
yarn add saracrm-web-sdk
# or
pnpm add saracrm-web-sdk

Usage in Next.js

App Router (Next.js 13+)

// app/page.tsx
import SaracrmChat from "saracrm-web-sdk";
import "saracrm-web-sdk/style.css";

export default function HomePage() {
  return (
    <div>
      <h1>My App</h1>
        <SaracrmChatClient
          apiBaseUrl={process.env.NEXT_PUBLIC_API_BASE_URL}
          pluginKey={process.env.NEXT_PUBLIC_PLUGIN_KEY}
        />
    </div>
  );
}

Pages Router (Next.js 12+)

// pages/index.tsx
import dynamic from 'next/dynamic';
import "saracrm-web-sdk/style.css";

// Dynamically import to avoid SSR issues
const SaracrmChat = dynamic(
  () => import("saracrm-web-sdk"),
  { ssr: false }
);

export default function HomePage() {
  return (
    <div>
      <h1>My App</h1>
      <SaracrmChat 
        apiKey="your-api-key"
        user={user}
      />
    </div>
  );
}

Usage in Regular React Apps

// App.jsx
import SaracrmChat from "saracrm-web-sdk";
import "saracrm-web-sdk/style.css";

function App() {
  return (
    <div>
      <h1>My App</h1>
      <SaracrmChat 
        apiKey="your-api-key"
        user={user}
      />
    </div>
  );
}

export default App;

Props

| Prop | Type | Required | Description | |------|------|----------|-------------| | apiKey | string | Yes | Your SaraCRM API key | | user | object | No | User information object | | token | string | No | Device token (auto-generated if not provided) |

Development

# Install dependencies
npm install

# Run development server (for testing the SDK in development)
npm run dev

# Build for production
npm run build

# Preview production build
npm run preview

# Create a package tarball for local testing
npm run pack

# Test the packaged SDK in another app
# (in your Next.js app)
npm install /path/to/saracrm-web-sdk-0.0.1.tgz

# Or publish to npm
npm publish

Publishing Workflow

1. Development: dist/ is in .gitignore to keep git clean
2. Building: Run npm run build to generate dist/
3. Testing: Run npm run pack to create a .tgz file
4. Publishing: npm publish automatically includes the dist/ folder (even though it's in .gitignore)
   • The "files": ["dist"] field in package.json ensures dist/ is included in the npm package
   • .npmignore excludes source files from the npm package

Build Output

The SDK is built as a library with:

• ESM: dist/saracrm-web-sdk.es.js (for modern bundlers)
• CJS: dist/saracrm-web-sdk.cjs.js (for CommonJS environments)
• CSS: dist/style.css (imported separately)

Technical Details

• Built with Vite and optimized for React 18/19
• Uses automatic JSX runtime for compatibility
• React hooks are SSR-safe with proper guards
• localStorage usage is protected with typeof window !== 'undefined' checks
• Peer dependencies include React, React DOM, and Redux Toolkit

Environment Variables

For development, create a .env file:

VITE_PLUGIN_KEY=your-plugin-key
VITE_API_BASE_URL=https://your-api-url.com

Support

For issues and questions, please contact support or open an issue on GitHub.

License

MIT