Getting Started with Spatio Platform CLI

The Spatio Platform CLI is a powerful command-line tool that enables developers to create, develop, build, and deploy custom platforms for Spatio. Platforms are full-stack applications consisting of a backend and a frontend user interface that embeds seamlessly into the main Spatio web app.

What Are Spatio Platforms?

Platforms are custom micro-frontends that run inside Spatio's shell application. They allow you to:

Build custom tools and interfaces for your team
Create vertical-specific applications (CRM, analytics, project management, etc.)
Extend Spatio's functionality with your own features
Access Spatio's APIs, workspaces, and connected providers

Each platform consists of:

Frontend: A React application that embeds into Spatio's UI
Backend: API endpoints and business logic for your platform
Configuration: Metadata defining capabilities and permissions

Installation

Prerequisites

Before installing the Spatio Platform CLI, ensure you have:

Node.js 18 or later
npm or yarn package manager
A Spatio account (sign up at spatiolabs.org)

Install via npm

npm install -g @spatio/platform-cli

Verify Installation

spatio --version

Authentication

Before creating or deploying platforms, authenticate with your Spatio account:

spatio login

This will open your browser to complete the authentication process.

Creating Your First Platform

Quick Start with Templates

The fastest way to get started is using one of our templates:

spatio create my-first-platform

You'll be prompted to choose from several templates:

Basic - Minimal setup to get started quickly
CRM - Customer relationship management template
Dashboard - Analytics dashboard template

Initialize in Existing Directory

If you already have a project directory:

cd my-platform
spatio init

This creates the necessary configuration files and structure.

Project Structure

After creation, your platform will have this structure:

my-first-platform/
├── src/
│   ├── frontend/          # React application
│   │   ├── App.tsx        # Main app component
│   │   ├── components/    # UI components
│   │   └── hooks/         # Custom hooks
│   └── backend/           # API endpoints
│       └── index.ts       # Backend entry point
├── spatio.config.json     # Platform configuration
├── package.json
└── tsconfig.json

Development Workflow

Start Development Server

Start the local development server with hot module reloading:

spatio dev

This starts:

Frontend dev server on http://localhost:3000
Backend dev server on http://localhost:3001
Watches for file changes and auto-reloads

Using the Platform SDK

Your frontend has access to the Spatio Platform SDK with powerful hooks:

import { useWorkspace, useSpatioAPI, useProviders } from '@spatio/platform-sdk';

function MyComponent() {
  const { workspace, user, organization } = useWorkspace();
  const api = useSpatioAPI();
  const providers = useProviders();

  // Access workspace data
  console.log('Current workspace:', workspace.name);

  // Make authenticated API calls
  const fetchData = async () => {
    const data = await api.get('/my-endpoint');
    return data;
  };

  // Access connected providers (Gmail, Salesforce, etc.)
  const gmailProvider = providers.find(p => p.type === 'gmail');

  return <div>Building with Spatio!</div>;
}

Platform Configuration

Edit spatio.config.json to configure your platform:

{
  "name": "my-first-platform",
  "displayName": "My First Platform",
  "description": "A custom platform for my team",
  "version": "1.0.0",
  "icon": "🚀",
  "capabilities": {
    "workspace": true,
    "providers": ["gmail", "salesforce"],
    "storage": true
  },
  "routes": {
    "main": "/",
    "settings": "/settings"
  }
}

Building for Production

Build Your Platform

Compile and bundle your platform for deployment:

spatio build

This creates optimized production builds:

Frontend bundle with code splitting
Backend compiled to Node.js
Source maps for debugging
Validation of platform configuration

Validate Before Deployment

Check for issues before deploying:

spatio validate

This checks:

Configuration validity
Required dependencies
Security vulnerabilities
API endpoint definitions
Frontend component structure

Deploying Your Platform

Deploy to Spatio

Deploy your platform to make it available to users:

spatio deploy

The deployment process:

Builds your platform
Validates the bundle
Uploads to Spatio's infrastructure
Makes it available to your organization
Provides a deployment URL

View Platform Information

Check your platform's status and details:

spatio info

This displays:

Platform name and version
Deployment status
Active users
API endpoint URLs
Last deployment time

Platform SDK Features

Core Hooks

useWorkspace() - Access workspace context

const { workspace, user, organization } = useWorkspace();

useSpatioAPI() - Make authenticated API calls

const api = useSpatioAPI();
const data = await api.get('/endpoint');

useProviders() - Access connected third-party providers

const providers = useProviders();
const gmail = providers.find(p => p.type === 'gmail');

useNavigation() - Navigate between platforms

const { navigate } = useNavigation();
navigate('/another-platform');

useStorage() - Persistent storage for your platform

const { data, setData } = useStorage('my-key');

useShellState() - Control the Spatio shell UI

const { setSidebarOpen, setFullscreen } = useShellState();

useEvents() - Inter-platform communication

const { emit, on } = useEvents();
emit('custom-event', { data: 'hello' });

Best Practices

1. Use TypeScript

All templates include TypeScript for type safety:

interface UserData {
  id: string;
  name: string;
  email: string;
}

const fetchUsers = async (): Promise<UserData[]> => {
  const api = useSpatioAPI();
  return api.get<UserData[]>('/users');
};

2. Handle Loading States

Always handle async operations gracefully:

function DataComponent() {
  const [data, setData] = useState(null);
  const [loading, setLoading] = useState(true);
  const api = useSpatioAPI();

  useEffect(() => {
    api.get('/data')
      .then(setData)
      .finally(() => setLoading(false));
  }, []);

  if (loading) return <div>Loading...</div>;
  return <div>{/* Render data */}</div>;
}

3. Leverage Spatio's Design System

Use consistent UI components:

import { Button, Card, Input } from '@spatio/design-system';

function MyForm() {
  return (
    <Card>
      <Input placeholder="Enter name" />
      <Button variant="primary">Submit</Button>
    </Card>
  );
}

4. Environment-Specific Configuration

Use environment variables for different deployments:

# Development
SPATIO_ENV=dev spatio dev

# Production
SPATIO_ENV=prod spatio deploy

Common Workflows

Adding a New Page

Create component in src/frontend/components/
Add route in spatio.config.json
Test with spatio dev
Deploy with spatio deploy

Adding a Backend Endpoint

Create endpoint in src/backend/
Export from src/backend/index.ts
Call from frontend using useSpatioAPI()
Test and deploy

Connecting to External Services

Use environment variables for API keys
Make calls from backend for security
Cache responses when possible
Handle errors gracefully

Integration with CI/CD

GitHub Actions

Automate deployments with GitHub Actions:

name: Deploy Platform
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Setup Node.js
        uses: actions/setup-node@v2
        with:
          node-version: '18'
      - name: Install Spatio CLI
        run: npm install -g @spatio/platform-cli
      - name: Install Dependencies
        run: npm install
      - name: Authenticate
        run: spatio login --api-key ${{ secrets.SPATIO_API_KEY }}
      - name: Build and Deploy
        run: spatio deploy

Troubleshooting

Development Server Issues

# Clear cache and restart
rm -rf node_modules .spatio-cache
npm install
spatio dev

Build Failures

# Run validation to identify issues
spatio validate

# Check for dependency issues
npm audit fix

Deployment Errors

# Verify authentication
spatio login

# Check platform info
spatio info

# Review build output
spatio build --verbose

Getting Help

View command help: spatio [command] --help
Check platform status: spatio info
Review logs during deployment

Next Steps

Now that you understand the Platform CLI basics, explore these topics:

The Spatio Platform CLI enables you to build powerful, custom tools that integrate seamlessly with Spatio's ecosystem. Start simple and expand your platform as your needs grow.

Happy building! 🚀