Frontend SDK

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	✅ Apache 2.0	✅	✅	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: '[email protected]', 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": "[email protected]", "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: '[email protected]', 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"
  }
}

This is the beginning of the README. Read the rest at the original. Read the full README ↗