Installation

Package Installation

The Composite Analytics SDK is available as a single npm package that works across all JavaScript environments.

npm
yarn
pnpm
bun

npm install @composite-inc/composite-js

CDN Installation

For quick prototypes or simple HTML pages, you can use the SDK directly from a CDN:

<script type="module">
  import composite from 'https://cdn.jsdelivr.net/npm/@composite-inc/composite-js@latest/+esm';

  await composite.init({
    apiKey: 'pk_your_api_key'
  });
</script>

For production environments, always pin to a specific version to avoid unexpected breaking changes.

TypeScript Support

The SDK includes TypeScript definitions out of the box:

import composite, { CompositeOptions, CompositeClient } from '@composite-inc/composite-js';

const options: CompositeOptions = {
  apiKey: 'pk_your_api_key',
  sessionRecording: true,
  debug: process.env.NODE_ENV === 'development'
};

const client: CompositeClient = await composite.init(options);

Type Definitions

interface CompositeOptions {
  // Required
  apiKey: string;

  // Optional features
  sessionRecording?: boolean | SessionRecordingOptions;

  // API configuration
  apiHost?: string;
  apiVersion?: string;

  // Transport
  transport?: 'default' | 'chrome-extension' | Transport;

  // Callbacks
  loaded?: (client: CompositeClient) => void;
  debug?: boolean;
}

interface SessionRecordingOptions {
  maskSelector?: string;
  blockSelector?: string;
  maskAllInputs?: boolean;
  maskTextSelector?: string;
  compress?: boolean;
  recordCanvas?: boolean;
  recordCrossOriginIframes?: boolean;
}

Build Tool Configuration

Webpack

// webpack.config.js
module.exports = {
  module: {
    rules: [
      {
        test: /\.js$/,
        exclude: /node_modules\/(?!@composite-inc/composite-js)/,
        use: {
          loader: 'babel-loader'
        }
      }
    ]
  },
  resolve: {
    alias: {
      '@composite-inc/composite-js': '@composite-inc/composite-js/dist/composite.esm.js'
    }
  }
};

Vite

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

export default defineConfig({
  optimizeDeps: {
    include: ['@composite-inc/composite-js']
  },
  build: {
    rollupOptions: {
      output: {
        manualChunks: {
          'analytics': ['@composite-inc/composite-js']
        }
      }
    }
  }
});

Rollup

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

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

Parcel

No configuration needed! Parcel works out of the box:

parcel build src/index.html

Environment-Specific Setup

Browser

Standard browser setup with module imports:

// app.js
import composite from '@composite-inc/composite-js';

window.addEventListener('DOMContentLoaded', async () => {
  await composite.init({
    apiKey: 'pk_your_api_key',
    sessionRecording: true
  });
});

Node.js

For server-side Node.js applications:

// server.js
import composite from '@composite-inc/composite-js';

// Initialize once when server starts
await composite.init({
  apiKey: process.env.COMPOSITE_API_KEY,
  transport: 'node'  // Uses Node-specific transport
});

// Identify users on the server
app.post('/api/login', async (req, res) => {
  // Process login...

  composite.identify(user.id, {
    email: user.email,
    plan: user.plan
  });
});

Electron

For Electron applications, initialize in both main and renderer processes:

// main.js (Main process)
const { app } = require('electron');
const composite = require('@composite-inc/composite-js').default;

app.whenReady().then(async () => {
  await composite.init({
    apiKey: 'pk_your_api_key',
    transport: 'electron-main'
  });
});

// renderer.js (Renderer process)
import composite from '@composite-inc/composite-js';

await composite.init({
  apiKey: 'pk_your_api_key',
  sessionRecording: true,
  transport: 'electron-renderer'
});

React Native

React Native support is currently in beta. Contact us for early access.

import composite from '@composite-inc/composite-js/native';

export default function App() {
  useEffect(() => {
    composite.init({
      apiKey: 'pk_your_api_key',
      transport: 'react-native'
    });
  }, []);

  return <View>...</View>;
}

Version Management

Checking Version

import composite from '@composite-inc/composite-js';

console.log('Composite SDK Version:', composite.version);
// Output: "1.0.0"

Upgrading

Check current version

npm list @composite-inc/composite-js

View available versions

npm view @composite-inc/composite-js versions --json

Upgrade to latest

npm update @composite-inc/composite-js

Or upgrade to specific version

npm install @composite-inc/composite-js@1.2.0

Bundle Size Optimization

The SDK uses dynamic imports for optional features to minimize bundle size:

Module	Size (gzipped)	Loaded
Core	~5KB	Always
Session Recording	~8KB	When `sessionRecording: true`
rrweb (dependency)	~200KB	When session recording is active

Tree Shaking

The SDK supports tree shaking. Import only what you need:

// Full SDK (recommended for most use cases)
import composite from '@composite-inc/composite-js';

// Or import specific functions
import { init, identify } from '@composite-inc/composite-js';

await init({ apiKey: 'pk_your_api_key', sessionRecording: true });
identify('user_id');

Lazy Loading

Session recording is automatically lazy-loaded:

// This doesn't load session recording code
await composite.init({
  apiKey: 'pk_your_api_key'
});

// This triggers lazy loading of session recording modules
composite.startSessionRecording();

Security Considerations

API Key Security

Never expose your secret API key (sk_*) in client-side code. Only use public keys (pk_*) in browsers.

// ✅ Correct: Use public key in browser
await composite.init({
  apiKey: 'pk_abc123'  // Public key
});

// ❌ Wrong: Never use secret key in browser
await composite.init({
  apiKey: 'sk_secret123'  // This exposes your secret key!
});

Content Security Policy

If your site uses CSP, add Composite’s API domain:

<meta http-equiv="Content-Security-Policy"
      content="connect-src 'self' https://prod.alb.us.api.composite.com;">

Subresource Integrity

When using CDN, add SRI for security:

<script
  src="https://cdn.jsdelivr.net/npm/@composite-inc/composite-js@1.0.0/dist/composite.min.js"
  integrity="sha384-oqVuAfXRKap7fdgcCY5uykM6+R9GJQ8SJiu+EQ4tLnYL3uwqyCx1tUr4CZm"
  crossorigin="anonymous">
</script>

Verification

After installation, verify the SDK is working:

import composite from '@composite-inc/composite-js';

// Initialize with session recording
await composite.init({
  apiKey: 'pk_your_api_key',
  sessionRecording: true,
  debug: true  // Enable debug logs
});

// Check console for debug output
// Check Network tab for API calls to prod.alb.us.api.composite.com

Troubleshooting

Module not found error

Ensure the package is installed:

npm install @composite-inc/composite-js

Clear your package manager cache:

npm cache clean --force
rm -rf node_modules package-lock.json
npm install

TypeScript errors

Update TypeScript to latest version:

npm install -D typescript@latest

Ensure moduleResolution is set correctly in tsconfig.json:

{
  "compilerOptions": {
    "moduleResolution": "node",
    "esModuleInterop": true
  }
}

Build errors with older bundlers

The SDK uses modern JavaScript features. Ensure your bundler supports:

ES2020 or later
Dynamic imports
Async/await

Or use the pre-built UMD bundle from CDN.

CORS errors with CDN

The CDN includes proper CORS headers. If you still see errors:

Check your CSP settings
Ensure you’re using HTTPS
Try a different CDN (unpkg, skypack)

Next Steps

Quickstart Guide

Get up and running in 5 minutes

Chrome Extensions

Special setup for browser extensions

Configuration

All configuration options

API Reference

Complete API documentation

Getting Started

Core Concepts

Integrations

Package Installation

CDN Installation

TypeScript Support

Type Definitions

Build Tool Configuration

Webpack

Vite

Rollup

Parcel

Environment-Specific Setup

Browser

Node.js

Electron

React Native

Version Management

Checking Version

Upgrading

Bundle Size Optimization

Tree Shaking

Lazy Loading

Security Considerations

API Key Security

Content Security Policy

Subresource Integrity

Verification

Troubleshooting

Next Steps

Quickstart Guide

Chrome Extensions

Configuration

API Reference

Getting Started

Core Concepts

Integrations

​Package Installation

​CDN Installation

​TypeScript Support

​Type Definitions

​Build Tool Configuration

​Webpack

​Vite

​Rollup

​Parcel

​Environment-Specific Setup

​Browser

​Node.js

​Electron

​React Native

​Version Management

​Checking Version

​Upgrading

​Bundle Size Optimization

​Tree Shaking

​Lazy Loading

​Security Considerations

​API Key Security

​Content Security Policy

​Subresource Integrity

​Verification

​Troubleshooting

​Next Steps

Quickstart Guide

Chrome Extensions

Configuration

API Reference

Package Installation

CDN Installation

TypeScript Support

Type Definitions

Build Tool Configuration

Webpack

Vite

Rollup

Parcel

Environment-Specific Setup

Browser

Node.js

Electron

React Native

Version Management

Checking Version

Upgrading

Bundle Size Optimization

Tree Shaking

Lazy Loading

Security Considerations

API Key Security

Content Security Policy

Subresource Integrity

Verification

Troubleshooting

Next Steps