@embeddable/sdk

@embeddable/sdk

A TypeScript/JavaScript SDK with React utilities and hooks for embeddable applications. Built with tree shaking support and modern development practices.

Features

• 🌳 Tree Shaking: Import only what you need
• 📦 TypeScript: Full TypeScript support with type definitions
• ⚛️ React Hooks: Custom hooks for common patterns
• 🛠️ Utilities: Useful utility functions
• 📱 Storage: Enhanced localStorage utilities
• 🌐 API Client: Type-safe API client with error handling
• 🧪 Well Tested: Comprehensive test coverage

Installation

npm install @embeddable/sdk
# or
yarn add @embeddable/sdk
# or
pnpm add @embeddable/sdk

Usage

Import Everything

import { useLocalStorage, debounce } from '@embeddable/sdk';

Import Specific Modules (Tree Shaking)

// Import only hooks
import { useLocalStorage } from '@embeddable/sdk/hooks';

// Import only utilities
import { debounce } from '@embeddable/sdk/utils';

Global Configuration

The SDK supports global configuration through the EmbeddableProvider context. This allows you to set a widgetId and version and mode once and access them throughout your application.

Setup

Wrap your application with the EmbeddableProvider:

import { EmbeddableProvider } from '@embeddable/sdk';
import type { EmbeddableConfig } from '@embeddable/sdk';

function App() {
  const config: EmbeddableConfig = {
    widgetId: 'my-widget-123',
    version: '1.0.0', // 'dev' | 'latest' | string
    mode: 'embeddable', // 'embeddable' | 'standalone' | 'preview'
    ignoreCache: false,
    lazyLoad: false,
    loader: true,
    _containerId: 'my-container-id',
    _shadowRoot: undefined,
  };

  return (
    <EmbeddableProvider config={config}>
      <YourAppComponents />
    </EmbeddableProvider>
  );
}

Using Global Configuration

Access the global configuration in any component:

import { useEmbeddableConfig, useApi } from '@embeddable/sdk';

function WidgetComponent() {
  const config = useEmbeddableConfig();
  const api = useApi(); // Automatically uses global config

  return (
    <div>
      <h2>Widget: {config.widgetId}</h2>
      <p>Version: {config.version}</p>
      <p>Mode: {config.mode}</p>
      <p>Ignore Cache: {config.ignoreCache ? 'Yes' : 'No'}</p>
      <p>Lazy Load: {config.lazyLoad ? 'Yes' : 'No'}</p>
      <p>Show Loader: {config.loader ? 'Yes' : 'No'}</p>
      {/* Your widget content */}
    </div>
  );
}

API Reference

Hooks

useLocalStorage<T>(key: string, initialValue: T, options?: LocalStorageOptions)

A React hook for localStorage with state synchronization across tabs.

import { useLocalStorage } from '@embeddable/sdk/hooks'

function MyComponent() {
  const [user, setUser, removeUser] = useLocalStorage('user', { name: '', email: '' })

  return (
    <div>
      <input
        value={user.name}
        onChange={(e) => setUser(prev => ({ ...prev, name: e.target.value }))}
      />
      <button onClick={removeUser}>Clear</button>
    </div>
  )
}

useDebounce<T>(value: T, delay: number)

A React hook that debounces a value.

import { useDebounce } from '@embeddable/sdk/hooks'

function SearchInput() {
  const [searchTerm, setSearchTerm] = useState('')
  const debouncedSearchTerm = useDebounce(searchTerm, 300)

  useEffect(() => {
    if (debouncedSearchTerm) {
      // Perform search
    }
  }, [debouncedSearchTerm])

  return <input onChange={(e) => setSearchTerm(e.target.value)} />
}

useApi(config: EmbeddableApiConfig)

A React hook for API calls with loading and error states.

import { useApi } from '@embeddable/sdk/hooks'

function DataComponent() {
  const api = useApi({ apiKey: 'your-api-key', baseUrl: 'https://api.example.com' })

  const fetchData = async () => {
    const response = await api.get('/users')
    if (response.success) {
      console.log(response.data)
    }
  }

  return (
    <div>
      {api.loading && <div>Loading...</div>}
      {api.error && <div>Error: {api.error}</div>}
      <button onClick={fetchData}>Fetch Data</button>
    </div>
  )
}

useEmbeddableConfig()

A React hook to access the global SDK configuration.

import { useEmbeddableConfig } from '@embeddable/sdk/hooks';

function MyWidget() {
  const config = useEmbeddableConfig();

  return (
    <div>
      <h3>Widget ID: {config.widgetId}</h3>
      <p>Version: {config.version}</p>
      <p>Mode: {config.mode}</p>
    </div>
  );
}

Note: This hook must be used within an EmbeddableProvider.

Utilities

debounce<T>(func: T, wait: number)

Creates a debounced function.

import { debounce } from '@embeddable/sdk/utils';

const debouncedSave = debounce(data => {
  // Save data
}, 500);

createApiClient(config: EmbeddableApiConfig)

Creates a type-safe API client.

import { createApiClient } from '@embeddable/sdk/utils';

const api = createApiClient({
  apiKey: 'your-api-key',
  baseUrl: 'https://api.example.com',
  debug: true,
});

const response = await api.get('/users');

storage

Enhanced localStorage utility with serialization support.

import { storage } from '@embeddable/sdk/utils';

// Basic usage
storage.set('user', { name: 'John', age: 30 });
const user = storage.get('user');

// With options
storage.set('data', complexObject, {
  prefix: 'myapp_',
  serialize: JSON.stringify,
  deserialize: JSON.parse,
});

Types

The SDK exports TypeScript types for better development experience:

import type {
  EmbeddableConfig,
  EmbeddableApiConfig,
  ApiResponse,
  LocalStorageOptions,
} from '@embeddable/sdk';

Development

# Install dependencies
npm install

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Build the package
npm run build

# Run linter
npm run lint

# Fix linting issues
npm run lint:fix

# Format code with Prettier
npm run format

# Check code formatting
npm run format:check

# Type check
npm run type-check

Contributing

• Fork the repository
• Create your feature branch (git checkout -b feature/amazing-feature)
• Commit your changes using conventional commits (git commit -m 'feat: add amazing feature')
• Push to the branch (git push origin feature/amazing-feature)
• Open a Pull Request

License

MIT © Embeddable Team

Changelog

See CHANGELOG.md for a list of changes.