Skip to content

README.md

Latest commit

 

History

History
347 lines (247 loc) · 9.28 KB

README.md

File metadata and controls

347 lines (247 loc) · 9.28 KB

SDK Kit

npm version npm downloads License: MIT TypeScript CI PRs Welcome Code of Conduct

Modern TypeScript framework for building JavaScript SDKs

SDK Kit provides a composable, plugin-based architecture for building type-safe, tree-shakeable JavaScript SDKs. Built with TypeScript and designed for modern development workflows, it offers the flexibility of a minimal core with the power of capability-based plugins.

Why SDK Kit?

Building a JavaScript SDK shouldn't mean starting from scratch every time. SDK Kit provides the foundational patterns and architecture that successful SDKs need:

  • Plugin Architecture - Functional, composable plugins with capability injection
  • Type-Safe - Full TypeScript support with inference and strict types
  • Tree-Shakeable - Build-time plugin exclusion for optimal bundle sizes
  • Framework-Agnostic - Works in vanilla JS, React, Vue, Svelte, or any framework
  • Event-Driven - Built-in event system with wildcard pattern matching
  • Zero Dependencies - Minimal footprint, maximum flexibility
  • Developer Experience - Intuitive API inspired by proven SDK patterns

Project Status

Core Framework:

  • Core SDK with functional plugin system
  • 6 capabilities (Emitter, Config, Namespace, Expose, Requirer, Extensible)
  • Plugin-to-plugin communication via hold()
  • 580+ tests with >90% coverage
  • Full TypeScript support

Essential Plugins:

  • Storage (localStorage/sessionStorage/cookies/memory)
  • Context (browser/device detection)
  • Poll (async resource polling)
  • Queue (batching & persistence)
  • Transport (fetch/beacon/pixel/XHR)
  • Consent (OneTrust/CookieBot)
  • Logging (Pino with privacy-first design)

See ROADMAP.md for what's next.

Project Structure

sdk-kit/
├── packages/
│   ├── core/              # @prosdevlab/sdk-kit - Core SDK framework ✅
│   ├── plugins/           # @prosdevlab/sdk-kit-plugins - Essential plugins ✅
│   └── testing/           # @prosdevlab/sdk-kit-testing - Testing utilities ✅
├── examples/
│   └── minimal-sdk/       # Working example SDK ✅
├── tests/
│   ├── integration/       # Integration tests ✅
│   └── e2e/              # End-to-end tests ✅
└── specs/                 # Feature specifications

Getting Started

Installation

Install SDK Kit from npm:

npm install @prosdevlab/sdk-kit
# or
yarn add @prosdevlab/sdk-kit
# or
pnpm add @prosdevlab/sdk-kit

Install with plugins:

npm install @prosdevlab/sdk-kit @prosdevlab/sdk-kit-plugins

Quick Start

import { SDK } from '@prosdevlab/sdk-kit';
import { storagePlugin } from '@prosdevlab/sdk-kit-plugins/storage';

const sdk = new SDK({
  name: 'my-sdk',
  version: '1.0.0'
});

sdk.use(storagePlugin);
await sdk.init();

// Use storage
sdk.storage.set('key', 'value');

Development Setup

Prerequisites:

Clone and build:

# Clone the repository
git clone https://github.com/prosdevlab/sdk-kit.git
cd sdk-kit

# Install dependencies
pnpm install

# Build all packages
pnpm build

Usage Examples

Basic SDK

See the minimal-sdk example for a complete working SDK.

import { SDK } from '@prosdevlab/sdk-kit';

// Create a simple plugin
function myPlugin(plugin, instance, config) {
  plugin.ns('my');
  plugin.defaults({ my: { setting: 'value' } });
  
  plugin.expose({
    greet(name) {
      plugin.emit('greeting', { name });
      return `Hello, ${name}!`;
    }
  });
  
  instance.on('sdk:ready', () => {
    console.log('SDK ready!');
  });
}

// Use the SDK
const sdk = new SDK({ my: { setting: 'custom' } });
sdk.use(myPlugin);
sdk.init();

sdk.greet('World'); // "Hello, World!"

Core Concepts

Functional Plugins

Plugins are functions that receive capabilities and compose functionality:

export default function myPlugin(plugin, instance, config) {
  plugin.ns('my.plugin');
  plugin.defaults({ my: { setting: 'default' } });
  
  plugin.expose({
    myMethod() {
      plugin.emit('my-event', { data: 'value' });
    }
  });
  
  instance.on('sdk:ready', () => {
    console.log('SDK initialized');
  });
}

Capability Injection

Plugins receive only the capabilities they need, enabling explicit dependency management and better tree-shaking:

interface Plugin extends Emitter, Defaulter, Namespaced, Exposer {}

Build-Time Optimization

Conditionally include plugins at build time for optimal bundle sizes:

// Only include what you need
if (!PLUGIN_EXCLUDED_STORAGE) {
  sdk.use(storagePlugin);
}

Documentation

Plugin Development Guide

Comprehensive guide for building SDK Kit plugins, covering:

  • Plugin Types - Storage-like, collectors, utilities, and orchestration plugins
  • Design Patterns - Capability injection, lazy initialization, graceful degradation
  • Testing Strategies - Unit tests, integration tests, and coverage targets
  • Best Practices - From 6 production plugins in the essential plugins package
  • Tier 1 vs Tier 2 - When to build generic vs. company-specific plugins

Perfect for developers building custom plugins or contributing to the core plugin library.

Development Workflow

Running Tests

# Run all tests (unit + integration)
pnpm test

# Run only unit tests
pnpm test:unit

# Run only integration tests
pnpm test:integration

# Run tests in watch mode
pnpm test:watch

# Run with coverage
pnpm test:coverage

Linting and Formatting

# Lint all packages
pnpm lint

# Format all packages
pnpm format

Building

# Build all packages
pnpm build

# Build a specific package
pnpm -F "@prosdevlab/sdk-kit" build

# Watch mode for development
pnpm -F "@prosdevlab/sdk-kit" dev

Type Checking

# Type check all packages
pnpm typecheck

Use Cases

  • Analytics SDKs - Event tracking, session management, user identification
  • Personalization SDKs - A/B testing, feature flags, dynamic content
  • Communication SDKs - Chat, notifications, webhooks
  • Data Collection SDKs - Form handling, validation, submission
  • Integration SDKs - Third-party API wrappers with local state

Architecture

SDK Kit is designed with the following principles:

  1. Composable - Build complex SDKs from simple, focused plugins
  2. Type-Safe - Catch errors at compile time, not runtime
  3. Efficient - Ship only what's needed with automatic tree-shaking
  4. Flexible - Work with any framework or none at all
  5. Testable - Isolated plugins are easy to test and maintain

Packages

@prosdevlab/sdk-kit

Core SDK framework with plugin system, event emitter, and configuration management.

Install: npm install @prosdevlab/sdk-kit

@prosdevlab/sdk-kit-plugins

Essential plugins for common SDK functionality (storage, context, poll, queue, transport, consent, logging).

Install: npm install @prosdevlab/sdk-kit-plugins

@prosdevlab/sdk-kit-testing

Testing utilities and mocks for building robust tests.

Examples

Minimal SDK ✅

A complete working example demonstrating:

  • Plugin registration and lifecycle
  • Configuration management
  • Event handling
  • Public API exposure
  • Runtime verification tests

Roadmap

See our ROADMAP.md for detailed development plans and timelines.

Contributing

We welcome contributions! Here's how to get involved:

Our workflow follows a spec-driven approach where detailed specifications live in the specs/ directory, and GitHub issues are used for tracking progress.

Making Changes

  1. Create a new branch

    git checkout -b feature/my-feature

  2. Make your changes

  3. Commit your changes using conventional commits

    git commit -m "feat: add new feature"

  4. Add a changeset to document your changes

    pnpm changeset

  5. Push your branch and create a pull request

License

MIT © prosdevlab

Built with insights from production SDKs serving millions of requests daily.