frontend-sdk

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

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

Available Packages

Core Infrastructure

Feature Blocks

Framework Bindings

Testing

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.