23blocks SDK

Build full-stack apps 10x faster with modular backend blocks

A type-safe TypeScript SDK for 23blocks backend-as-a-service. Authentication, payments, CRM, e-commerce, and 15+ more blocks ready to use.

Documentation • Website • Issues

Features

• Modular architecture - Install only the blocks you need
• Framework agnostic - Core packages work with any JavaScript framework
• First-class TypeScript - Full type safety with comprehensive type definitions
• Angular & React bindings - Native integrations with RxJS Observables and React hooks
• JSON:API compliant - Built on the JSON:API v1.0 specification
• Debug logging - Built-in request/response logging for development
• Request tracing - Automatic request IDs for debugging and support
• Automatic retries - Exponential backoff with jitter for transient failures
• Interceptors - Hook into request/response lifecycle for cross-cutting concerns

Why 23blocks?

Stop rebuilding the same backend features for every project. 23blocks provides production-ready building blocks:

Challenge	23blocks Solution
Building auth from scratch	Ready-to-use authentication with MFA, OAuth, roles, API keys
Weeks on CRUD operations	Pre-built blocks for CRM, products, content, forms
Complex payment integrations	Wallet and sales blocks with transaction support
Framework lock-in	Works with React, Angular, Next.js, Vue, or vanilla JS
Inconsistent API responses	JSON:API v1.0 compliant, predictable data structures
Debugging production issues	Built-in request tracing with unique IDs

Perfect for building: SaaS applications • E-commerce platforms • Marketplaces • Internal tools • Mobile app backends • Multi-tenant systems

The LEGO Philosophy: One SDK, Any Backend

This SDK is built on contracts, not dependencies. Use 23blocks services or bring your own backend — as long as it speaks the same language, it just works.

// Use 23blocks managed services
const client = create23BlocksClient({
  urls: { authentication: 'https://api.23blocks.com' },
  apiKey: 'your-api-key',
});

// OR use your own backend
const client = create23BlocksClient({
  urls: { authentication: 'https://your-api.com' },
  apiKey: 'your-api-key',
});

// Same SDK. Same code. Same types.
// Your backend just needs to implement the JSON:API contract.

Approach	Description
JSON:API Contract	Every endpoint follows the JSON:API specification. Standardized request/response formats mean predictable, reliable integrations.
Swap Any Backend	Using 23blocks Auth today but want to build your own? Implement the contract, point the SDK at your server, done. Zero frontend changes.
No Vendor Lock-in	The contract is open. The SDK is open. Your architecture remains yours — we're just making it easier to build.

Build your own backend? The contract defines endpoints, models, and response formats. Implement it in Rails, Node, Go, Python, or any language you prefer. See our Contract Specification for details.

Comparison

Feature	23blocks	Firebase	Supabase	Custom Backend
Type-safe SDK	✅	⚠️ Partial	✅	❌ Build yourself
Modular architecture	✅ 18+ blocks	❌ Monolithic	⚠️ Limited	❌ Build yourself
React hooks	✅ Native	⚠️ Community	✅	❌ Build yourself
Angular services	✅ Native RxJS	⚠️ Community	❌	❌ Build yourself
JSON:API compliant	✅	❌	❌	❌ Build yourself
Request tracing	✅ Built-in	❌	❌	❌ Build yourself
Self-hostable	✅	❌	✅	✅
Bring your own backend	✅ Contract-based	❌ Locked	❌ Locked	N/A
Open source SDK	✅ MIT	✅	✅	N/A

Quick Start

npm install @23blocks/sdk

import { create23BlocksClient } from '@23blocks/sdk';

// Create client - that's it!
const client = create23BlocksClient({
  urls: { authentication: 'https://api.yourapp.com' },
  apiKey: 'your-api-key',
});

// Sign in - tokens are stored automatically
await client.auth.signIn({ email: 'user@example.com', password: 'password' });

// All subsequent requests include auth automatically
const products = await client.products.products.list();
const user = await client.auth.getCurrentUser();

// Sign out - tokens are cleared automatically
await client.auth.signOut();

Works with any compatible backend! Use 23blocks managed services for instant setup, or implement the JSON:API contract on your own servers.

See Installation Guide for detailed options.

Debug Mode

Enable debug logging to see all requests and responses in your console:

import { create23BlocksClient } from '@23blocks/sdk';

const client = create23BlocksClient({
  urls: { authentication: 'https://api.yourapp.com' },
  apiKey: 'your-api-key',
  debug: true,  // Enable debug logging
});

Console output:

[23blocks] POST /auth/sign_in [req_m5abc_xyz123]
[23blocks] → Headers: { "x-api-key": "***", "content-type": "application/json" }
[23blocks] → Body: { "email": "user@example.com", "password": "***" }
[23blocks] ← 200 OK (145ms) [req_m5abc_xyz123]

Error Handling with Request Tracing

Every error includes a unique request ID for easy debugging:

import { isBlockErrorException } from '@23blocks/contracts';

try {
  await client.auth.signIn({ email: 'user@example.com', password: 'wrong' });
} catch (error) {
  if (isBlockErrorException(error)) {
    console.log('Request ID:', error.requestId);  // "req_m5abc_xyz123"
    console.log('Duration:', error.duration);      // 145 (ms)
    console.log('Message:', error.message);        // "Invalid credentials"

    // Send to support: "Please check request req_m5abc_xyz123"
  }
}

Documentation

Guide	Description
Installation	Full SDK vs individual packages
Angular	Setup with Injectable services and RxJS
Next.js / React	Setup with hooks and context
Vanilla TypeScript	Framework-agnostic usage

Available Packages

Core Infrastructure

Package	Description
@23blocks/contracts	Core types and interfaces
@23blocks/jsonapi-codec	JSON:API encoder/decoder
@23blocks/transport-http	HTTP transport layer

Feature Blocks

Package	Description
@23blocks/block-authentication	Auth, users, roles, API keys
@23blocks/block-search	Full-text search, favorites
@23blocks/block-products	Product catalog, categories, variants
@23blocks/block-crm	Contacts, organizations, deals
@23blocks/block-content	CMS content, pages, media
@23blocks/block-geolocation	Addresses, places, geocoding
@23blocks/block-conversations	Messaging, threads, notifications
@23blocks/block-files	File uploads, storage
@23blocks/block-forms	Form builder, submissions
@23blocks/block-assets	Asset management, tracking
@23blocks/block-campaigns	Marketing campaigns, audiences
@23blocks/block-company	Company settings, branding
@23blocks/block-rewards	Loyalty programs, points
@23blocks/block-sales	Orders, invoices, payments
@23blocks/block-wallet	Digital wallet, transactions
@23blocks/block-jarvis	AI assistant integration
@23blocks/block-onboarding	User onboarding flows
@23blocks/block-university	Learning management, courses

Framework Bindings

Package	Description
@23blocks/angular	Angular services with RxJS Observables
@23blocks/react	React hooks and context provider
@23blocks/sdk	Meta-package with all blocks

Testing

Package	Description
@23blocks/testing	Mock transport, fixtures, and assertion helpers

Architecture

┌─────────────────────────────────────────────────────────────┐
│  Framework Bindings                                         │
│  ┌──────────────────┐  ┌──────────────────┐                │
│  │ @23blocks/angular│  │ @23blocks/react  │                │
│  │ (RxJS Observables)  │ (hooks, context) │                │
│  └────────┬─────────┘  └────────┬─────────┘                │
└───────────┼─────────────────────┼──────────────────────────┘
            │                     │
┌───────────▼─────────────────────▼──────────────────────────┐
│  Blocks (Promise-based, framework agnostic)                │
│  ┌────────────────┐ ┌────────────────┐ ┌────────────────┐  │
│  │ authentication │ │    search      │ │   products     │  │
│  └────────────────┘ └────────────────┘ └────────────────┘  │
│  ┌────────────────┐ ┌────────────────┐ ┌────────────────┐  │
│  │      crm       │ │    content     │ │    + more      │  │
│  └────────┬───────┘ └────────┬───────┘ └────────┬───────┘  │
└───────────┼──────────────────┼──────────────────┼──────────┘
            │                  │                  │
┌───────────▼──────────────────▼──────────────────▼──────────┐
│  Core Infrastructure                                        │
│  ┌────────────┐ ┌──────────────┐ ┌──────────────────┐      │
│  │ contracts  │ │jsonapi-codec │ │  transport-http  │      │
│  └────────────┘ └──────────────┘ └──────────────────┘      │
└─────────────────────────────────────────────────────────────┘

Requirements

• Node.js >= 18.0.0
• TypeScript >= 5.0 (for TypeScript users)
• Angular >= 10 (for @23blocks/angular)
• React >= 18 (for @23blocks/react)

Contributing

We welcome contributions! Please see our Development Guide for details.

Support the Project

If 23blocks SDK helps you build faster, consider giving us a star! It helps others discover the project and motivates us to keep improving.

License

MIT - Copyright (c) 2024 23blocks