✨ Features

• 🗄️ Dynamic Database Management — Create and modify data models on the fly with a flexible schema system
• 🔍 Powerful Query API — Complex filtering, sorting, pagination, aggregation, and full-text search
• 🔐 Authentication & Authorization — JWT, cookie-based auth, SSO providers, and role-based permissions
• ✅ Schema Validations — Built-in field validation with min/max, patterns, required, unique, and custom rules
• ⚡ Workflow Automation — Visual workflow builder with 17 node types and real-time monitoring
• 🔔 Notification System — Built-in user notifications with real-time delivery via Socket.IO
• 📁 File Storage & Processing — Upload, manage, and transform files with image optimization
• 📝 Pino Logger — High-performance structured logging with configurable transports (Datadog, Loki, etc.)
• 🌍 PostGIS Geospatial Support — Advanced spatial data operations
• 📊 Reporting & Analytics — Generate complex reports with grouping and aggregation
• 🪝 Hooks System — Extend functionality with custom hooks on CRUD operations
• 🏢 Multi-tenant Architecture — Host multiple isolated organizations in a single instance
• ⚡ Real-time Updates — Socket.IO integration with Redis clustering, plus WAL-based CDC for database changes
• 🚀 High Performance — Redis-based caching with configurable TTL
• 🖥️ CLI Tools — Project scaffolding, TypeScript type generation, and migration management
• ✉️ Email Template Designer — Visual drag-and-drop email template editor with variable placeholders

📦 JavaScript SDK

The official JavaScript/TypeScript SDK for Baasix provides a type-safe, easy-to-use client for web, Node.js, and React Native applications.

👉 GitHub: baasix/baasix | npm: @baasix/sdk

Installation

npm install @baasix/sdk

Quick Example

import { createBaasix } from '@baasix/sdk';

// Create client
const baasix = createBaasix({
  url: 'https://your-baasix-instance.com',
});

// Login
const { user } = await baasix.auth.login({
  email: '[email protected]',
  password: 'password123',
});

// Query items with type-safe filters
const { data: products } = await baasix.items('products').find({
  filter: { status: { eq: 'active' }, price: { gte: 10 } },
  sort: { createdAt: 'desc' },
  limit: 10,
});

// Create item
const productId = await baasix.items('products').create({
  name: 'New Product',
  price: 29.99,
});

// Real-time subscriptions
import { io } from 'socket.io-client';
baasix.realtime.setSocketClient(io);
await baasix.realtime.connect();

baasix.realtime.subscribe('products', (payload) => {
  console.log(`Product ${payload.action}:`, payload.data);
});

WAL-Based Realtime (PostgreSQL Logical Replication)

For production environments, Baasix supports PostgreSQL's Write-Ahead Log (WAL) for capturing database changes at the database level. This catches ALL changes including direct SQL, migrations, and external tools.

PostgreSQL Configuration:

-- In postgresql.conf:
wal_level = logical
max_replication_slots = 4
max_wal_senders = 4

Environment Variables:

SOCKET_ENABLED=true
REALTIME_WAL_ENABLED=true

Enable realtime for a collection:

# Via API (admin only)
POST /realtime/collections/products/enable
{ "replicaIdentityFull": true }  # Optional: enables old values on UPDATE/DELETE

SDK Features

• 🌐 Universal — Works in browsers, Node.js, and React Native
• 🔐 Flexible Auth — JWT tokens, HTTP-only cookies, OAuth (Google, Facebook, Apple, GitHub)
• 💾 Customizable Storage — LocalStorage, AsyncStorage, or custom adapters
• 📝 Type-Safe — Full TypeScript support with generics
• 📡 Realtime — WebSocket subscriptions for live data updates
• ⚡ Query Builder — Fluent API for complex queries with 50+ filter operators

React Native Setup

import { createBaasix, AsyncStorageAdapter } from '@baasix/sdk';
import AsyncStorage from '@react-native-async-storage/async-storage';

const baasix = createBaasix({
  url: 'https://api.example.com',
  storage: new AsyncStorageAdapter(AsyncStorage),
});

For complete SDK documentation, see the SDK README.

🖥️ CLI (Command-Line Interface)

The official CLI for Baasix provides project scaffolding, TypeScript type generation, extension creation, and migration management.

👉 npm: baasix

Installation

# Global installation
npm install -g baasix

# Or use with npx
npx baasix <command>

Commands

| Command | Description | |---------|-------------| | baasix init | Create a new project with interactive configuration | | baasix generate | Generate TypeScript types from your schemas | | baasix extension | Scaffold a new hook or endpoint extension | | baasix migrate | Run database migrations |

Quick Start with CLI

# Create a new API project
npx baasix init --template api my-api

# Or with interactive prompts for full configuration
npx baasix init

# Skip all prompts with sensible defaults
npx baasix init --template api -y

Project Templates

| Template | Description | |----------|-------------| | api | Standalone Baasix API server | | nextjs-app | Next.js 14+ frontend (App Router) with SDK | | nextjs | Next.js frontend (Pages Router) with SDK |

Note: Next.js templates create frontend-only projects that connect to a separate Baasix API.

Generate TypeScript Types

The CLI generates fully-typed interfaces with proper relation types and enum support:

# Generate types from running Baasix instance
baasix generate --url http://localhost:8056 --output ./src/types/baasix.d.ts

Generated types include:

• ✅ Relations typed as target collection types (not unknown)
• ✅ Enums as union types ('published' | 'draft' | 'archived')
• ✅ System collections (BaasixUser, BaasixRole, BaasixFile)
• ✅ Validation JSDoc comments (@min, @max, @length)

// Example generated types
export interface Product {
  id: string;
  name: string;
  status: 'published' | 'draft' | 'archived';  // Enum as union
  category?: Category | null;                   // Relation typed correctly
  userCreated?: BaasixUser | null;             // System relation
}

Create Extensions

# Create a new hook extension
baasix extension --type hook --name order-notifications --collection orders

# Create a new endpoint extension  
baasix extension --type endpoint --name analytics

Manage Migrations

# Create a migration
baasix migrate create --name add-products-table

# Check status
baasix migrate status --url http://localhost:8056

# Run pending migrations
baasix migrate run --url http://localhost:8056

For complete CLI documentation, see baasix.com/docs/cli-guide.

🚀 Quick Start

1. Create a new project

mkdir my-baasix-app
cd my-baasix-app
npm init -y

2. Install Baasix

npm install @baasix/baasix

3. Create server.js

import { startServer } from "@baasix/baasix";

// Basic usage - pretty printing in dev, JSON in production
startServer().catch((error) => {
  console.error("Failed to start server:", error);
  process.exit(1);
});

// With custom logger configuration
startServer({
  port: 8056,
  logger: {
    level: "info",      // 'fatal' | 'error' | 'warn' | 'info' | 'debug' | 'trace'
    pretty: true,       // Human-readable output (default in development)
  }
});

4. Configure package.json

{
  "type": "module",
  "scripts": {
    "start": "tsx server.js",
    "dev": "tsx watch server.js"
  },
  "devDependencies": {
    "tsx": "^4.16.0"
  }
}

5. Create .env file

# Database
DATABASE_URL="postgresql://postgres:yourpassword@localhost:5432/baasix"

# Server
PORT=8056
SECRET_KEY=your-secret-key-min-32-chars

# Cache (optional - defaults to memory)
# CACHE_ADAPTER=redis
# CACHE_REDIS_URL=redis://localhost:6379

# Real-time (optional)
# SOCKET_ENABLED=true
# SOCKET_REDIS_ENABLED=true        # For multi-instance
# SOCKET_REDIS_URL=redis://localhost:6379

# Background Tasks (optional)
# TASK_SERVICE_ENABLED=true
# TASK_REDIS_ENABLED=true          # For multi-instance
# TASK_REDIS_URL=redis://localhost:6379

# File Upload (optional)
# MAX_UPLOAD_FILE_SIZE=50          # Default: 50MB, set to 100 for 100MB

Multi-Instance Deployments: When running multiple instances (PM2 cluster, Kubernetes, etc.), enable Redis for Socket.IO and Tasks to ensure proper coordination. See the Deployment Guide for details.

6. Start the server

npm start

Visit http://localhost:8056/ to verify the server is running.

📋 Requirements

• Node.js 18+
• PostgreSQL 14+ with PostGIS extension
• Redis 6+

📚 Documentation

Full documentation is available at baasix.com/docs

Popular Guides

• Deployment Guide — Docker, PM2, Kubernetes deployment
• Database Schema Guide — Schema system and relationships
• Authentication Guide — Auth setup and SSO providers
• Extensions Guide — Create custom hooks and endpoints
• Advanced Query Guide — Complex filtering and aggregation

📦 Sample Project

Get started quickly with our complete sample project:

👉 github.com/baasix/baasix/samples/sample

Includes:

• Ready-to-use server configuration
• Docker deployment files
• PM2 ecosystem configurations
• Kubernetes manifests
• Example extensions (hooks & endpoints)
• MCP configuration files for AI-powered development

🤖 MCP Server (AI Integration)

Baasix includes Model Context Protocol (MCP) support for AI assistants like Claude, GitHub Copilot, and Cursor. Choose between Remote MCP (built-in) or Local MCP (npm package).

| Type | Description | Best For | |------|-------------|----------| | Remote MCP | Built-in HTTP endpoint at /mcp | Production, cloud, remote servers | | Local MCP | @baasix/mcp npm package | Claude Desktop, local development |

Features

• 57 MCP Tools for comprehensive Baasix operations
• Schema Management — Create, update, delete collections and relationships
• CRUD Operations — Full item management with powerful query capabilities
• 50+ Filter Operators — From basic comparison to geospatial and JSONB queries
• Permissions — Role-based access control management
• Authentication — Login, register, magic links, invitations

Remote MCP Setup (Recommended)

Enable the built-in MCP server:

# In your Baasix .env file
MCP_ENABLED=true
# MCP_PATH=/mcp  # Optional: customize the endpoint path

For Claude Code / Anthropic CLI — Create .mcp.json in your project:

{
  "mcpServers": {
    "baasix": {
      "type": "http",
      "url": "http://localhost:8056/mcp",
      "headers": {
        "X-MCP-Email": "[email protected]",
        "X-MCP-Password": "admin@123"
      }
    }
  }
}

For VS Code with GitHub Copilot — Create .vscode/mcp.json:

{
  "servers": {
    "baasix": {
      "type": "http",
      "url": "http://localhost:8056/mcp",
      "headers": {
        "X-MCP-Email": "${input:mcpEmail}",
        "X-MCP-Password": "${input:mcpPassword}"
      }
    }
  },
  "inputs": [
    { "id": "mcpEmail", "type": "promptString", "description": "Email" },
    { "id": "mcpPassword", "type": "promptString", "description": "Password", "password": true }
  ]
}

Local MCP Setup

For Claude Desktop or local stdio-based integrations:

👉 Local MCP Package | npm: @baasix/mcp

For Claude Desktop — Add to claude_desktop_config.json:

{
  "mcpServers": {
    "baasix": {
      "command": "npx",
      "args": ["@baasix/mcp"],
      "env": {
        "BAASIX_URL": "http://localhost:8056",
        "BAASIX_EMAIL": "[email protected]",
        "BAASIX_PASSWORD": "admin@123"
      }
    }
  }
}

For more configuration options and examples, see the MCP Server documentation.

🔧 Extensions

Extend Baasix with custom hooks and endpoints:

// extensions/baasix-hook-example/index.js
import { ItemsService } from "@baasix/baasix";

export default (hooksService, context) => {
  hooksService.registerHook("posts", "items.create", async ({ data, accountability }) => {
    data.created_by = accountability.user.id;
    data.created_at = new Date();
    return { data };
  });
};

// extensions/baasix-endpoint-example/index.js
import { APIError } from "@baasix/baasix";

export default {
  id: "custom-endpoint",
  handler: (app, context) => {
    app.get("/custom", async (req, res, next) => {
      res.json({ message: "Hello from custom endpoint!" });
    });
  },
};

🛠️ Available Exports

// Server
import { startServer, app } from "@baasix/baasix";

// Services
import { 
  ItemsService, 
  FilesService, 
  MailService,
  NotificationService,
  PermissionService,
  WorkflowService 
} from "@baasix/baasix";

// Utilities
import { 
  APIError, 
  env, 
  schemaManager,
  getDatabase,
  getSqlClient 
} from "@baasix/baasix";

// Logger
import { getLogger, initializeLogger } from "@baasix/baasix";

🤝 Contributing

Contributions are welcome! Please visit our GitHub repository to:

• Report bugs
• Request features
• Submit pull requests

📄 License

This package contains components with different licenses:

| Component | License | Open Source | |-----------|---------|-------------| | Core API & Backend | MIT | ✅ Yes | | Plugins & Utilities | MIT | ✅ Yes | | Admin Dashboard (app/) | Proprietary | ❌ No |

See the LICENSE.MD file for complete details.