https://github.com/23blocks-os/frontend-sdk

TypeScript SDK for 23blocks backend-as-a-service. Build apps 10x faster with modular blocks for auth, payments, CRM, e-commerce & more. React hooks + Angular services. JSON:API compliant.
https://github.com/23blocks-os/frontend-sdk

angular-services api-client authentication baas backend-as-a-service crm developer-tools ecommerce headless-backend javascript jsonapi modular-architecture nextjs nodejs open-source react-hooks saas typescript-sdk

Last synced: 7 days ago
JSON representation

TypeScript SDK for 23blocks backend-as-a-service. Build apps 10x faster with modular blocks for auth, payments, CRM, e-commerce & more. React hooks + Angular services. JSON:API compliant.

Host: GitHub
URL: https://github.com/23blocks-os/frontend-sdk
Owner: 23blocks-OS
License: mit
Created: 2025-12-13T02:21:02.000Z (about 1 month ago)
Default Branch: main
Last Pushed: 2026-01-16T17:45:16.000Z (9 days ago)
Last Synced: 2026-01-16T20:05:38.019Z (9 days ago)
Topics: angular-services, api-client, authentication, baas, backend-as-a-service, crm, developer-tools, ecommerce, headless-backend, javascript, jsonapi, modular-architecture, nextjs, nodejs, open-source, react-hooks, saas, typescript-sdk
Language: TypeScript
Homepage: https://23blocks.com/frontend-sdk
Size: 2.32 MB
Stars: 3
Watchers: 0
Forks: 1
Open Issues: 0
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Security: SECURITY.md

Awesome Lists containing this project

README

          


  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](https://jsonapi.org/) 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.

```typescript

// 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](https://jsonapi.org/). 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](https://23blocks.com/frontend-sdk) 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

```bash

npm install @23blocks/sdk

```

```typescript

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](https://23blocks.com) for instant setup, or implement the [JSON:API contract](https://23blocks.com/frontend-sdk) on your own servers.

See [Installation Guide](./docs/installation.md) for detailed options.

## Debug Mode

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

```typescript

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:

```typescript

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](./docs/installation.md) | Full SDK vs individual packages |

| [Angular](./docs/angular.md) | Setup with Injectable services and RxJS |

| [Next.js / React](./docs/nextjs.md) | Setup with hooks and context |

| [Vanilla TypeScript](./docs/vanilla.md) | 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](./DEVELOPMENT.md) 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](./LICENSE) - Copyright (c) 2024 23blocks

ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/23blocks-os/frontend-sdk

Awesome Lists containing this project

README

23blocks SDK