Client Libraries

Client Libraries

Cloudillo provides a comprehensive set of TypeScript/JavaScript client libraries for building applications. These libraries handle authentication, API communication, real-time synchronization, and React integration.

Available Libraries

@cloudillo/base

Core SDK for initialization and API access. This is the foundation for all Cloudillo applications.

Key Features:

  • App initialization and shell communication
  • Type-safe REST API client
  • CRDT document opening
  • Real-time database connection
  • Message bus subscription
  • WebSocket helpers

Install:

pnpm add @cloudillo/base

@cloudillo/react

React hooks and components for Cloudillo integration.

Key Features:

  • useAuth() hook for authentication state
  • useApi() hook for API client access
  • CloudilloProvider context provider
  • MicrofrontendContainer component
  • Profile and UI components

Install:

pnpm add @cloudillo/react

@cloudillo/types

Shared TypeScript types with runtime validation using @symbion/runtype.

Key Features:

  • All data types (Profile, Action, File, etc.)
  • Runtime type validation
  • Compile-time type safety
  • Action type enums
  • Type guards and validators

Install:

pnpm add @cloudillo/types

@cloudillo/rtdb

Real-time database client with Firebase-like API.

Key Features:

  • Firebase-like API (familiar to developers)
  • Real-time subscriptions
  • Type-safe queries
  • Batch operations
  • Computed values

Install:

pnpm add @cloudillo/rtdb

Quick Comparison

Library Purpose Use When
@cloudillo/base Core functionality Every app
@cloudillo/react React integration Building React apps
@cloudillo/types Type definitions TypeScript projects
@cloudillo/rtdb Real-time database Need structured real-time data

Installation

Minimal Setup (vanilla JS)

pnpm add @cloudillo/base

React Setup

pnpm add @cloudillo/base @cloudillo/react @cloudillo/types

Full Setup (with real-time features)

pnpm add @cloudillo/base @cloudillo/react @cloudillo/types @cloudillo/rtdb yjs y-websocket

Basic Usage

With @cloudillo/base

import * as cloudillo from '@cloudillo/base'

// Initialize
await cloudillo.init('my-app')

// Create API client
const api = cloudillo.createApiClient()

// Make requests
const profile = await api.me.get()

With @cloudillo/react

import { CloudilloProvider, useAuth, useApi } from '@cloudillo/react'

function App() {
  return (
    <CloudilloProvider appName="my-app">
      <MyComponent />
    </CloudilloProvider>
  )
}

function MyComponent() {
  const auth = useAuth()
  const api = useApi()

  // Use auth and api...
}

With @cloudillo/rtdb

import { RtdbClient } from '@cloudillo/rtdb'

const rtdb = new RtdbClient({
  fileId: 'my-db',
  token: 'your-token',
  url: 'wss://server.com/ws/rtdb'
})

const todos = rtdb.collection('todos')
todos.onSnapshot(snapshot => console.log(snapshot))

Common Patterns

Pattern 1: Authentication Flow

import * as cloudillo from '@cloudillo/base'

// Initialize (gets token from shell or manual setup)
const token = await cloudillo.init('my-app')

// Access global auth state
console.log(cloudillo.idTag) // User's identity
console.log(cloudillo.tnId) // Tenant ID
console.log(cloudillo.roles) // User roles

Pattern 2: API Requests

import * as cloudillo from '@cloudillo/base'

const api = cloudillo.createApiClient()

// GET request
const profile = await api.me.get()

// POST request
const action = await api.action.post({
  type: 'POST',
  content: { text: 'Hello!' }
})

// Query parameters
const actions = await api.action.get({
  type: 'POST',
  _limit: 20
})

Pattern 3: Real-Time Updates

import * as cloudillo from '@cloudillo/base'
import * as Y from 'yjs'

// Open CRDT document
const yDoc = new Y.Doc()
const { provider } = await cloudillo.openYDoc(yDoc, 'doc-id')

// Use shared types
const yText = yDoc.getText('content')
yText.insert(0, 'Hello!')

// Listen for changes
yText.observe(() => {
  console.log('Text updated:', yText.toString())
})

Pattern 4: React Integration

import { CloudilloProvider, useAuth, useApi } from '@cloudillo/react'
import { useEffect, useState } from 'react'

function PostsList() {
  const api = useApi()
  const [posts, setPosts] = useState([])

  useEffect(() => {
    api.action.get({ type: 'POST', _limit: 20 })
      .then(setPosts)
  }, [api])

  return (
    <div>
      {posts.map(post => (
        <div key={post.actionId}>{post.content.text}</div>
      ))}
    </div>
  )
}

TypeScript Support

All libraries are written in TypeScript and provide full type definitions.

import type { Profile, Action, NewAction } from '@cloudillo/types'

// Types are automatically inferred
const api = cloudillo.createApiClient()
const profile: Profile = await api.me.get()

// Type-safe action creation
const newAction: NewAction = {
  type: 'POST',
  content: { text: 'Hello!' }
}

const created: Action = await api.action.post(newAction)

Error Handling

All libraries use the FetchError class for API errors:

import { FetchError } from '@cloudillo/base'

try {
  const api = cloudillo.createApiClient()
  const data = await api.me.get()
} catch (error) {
  if (error instanceof FetchError) {
    console.error('Status:', error.status) // HTTP status code
    console.error('Code:', error.code) // Error code (e.g., 'E-AUTH-UNAUTH')
    console.error('Message:', error.message)
  }
}

Library Details

Explore each library in detail:

Next Steps