Skip to content

QUICKSTART.md

Latest commit

 

History

History
348 lines (274 loc) · 7.32 KB

QUICKSTART.md

File metadata and controls

348 lines (274 loc) · 7.32 KB
Raw

SDUI Quick Start Guide

Get your SDUI system up and running in 3 steps!

🚀 Step-by-Step Setup

Step 1: Start the Server (Terminal 1)

cd src/sdui/server
npm install
npm run dev

✅ You should see:

SDUI Server running on port 3001
WebSocket server ready for connections

Step 2: Start the Playground (Terminal 2)

cd src/sdui/playground
npm install
npm run dev

✅ Browser should open at http://localhost:5173

Step 3: Configure & Run Your App

A. Find Your IP Address

macOS/Linux:

ifconfig | grep "inet " | grep -v 127.0.0.1

Windows:

ipconfig

Look for something like: 192.168.1.100 (your local IP)

B. Update Server URLs

Replace YOUR_IP with your actual IP address in these files:

1. src/sdui/SDUIApp.tsx (lines 39, 44):

fetch('http://YOUR_IP:3001/api/sdui/screen', ...)
WebSocketService.connect('ws://YOUR_IP:3001');

2. src/sdui/core/ActionHandler.ts (lines 28, 49):

fetch('http://YOUR_IP:3001/api/sdui/action', ...)

C. Update Main App

Option 1: Replace Main App (Testing)

Edit App.tsx:

import SDUIApp from './src/sdui/SDUIApp';

function App(): React.JSX.Element {
  return <SDUIApp />;
}

export default App;

Option 2: Add as Tab (Integration)

Add to your existing navigation:

import { SDUIApp } from './src/sdui';

<Tab.Screen name="SDUI" component={SDUIApp} />

D. Run React Native App (Terminal 3)

# iOS
npm run ios

# Android
npm run android

🎮 Testing the System

  1. App Loads ✅

    • You should see "SDUI Demo App" header
    • Welcome text
    • Two buttons
    • Empty list

  2. Test Actions 🎯

    • Click "Show Alert" → Alert should appear
    • Click "Fetch Data" → List populates with 3 items

  3. Test Playground 🎨

    • Open playground at http://localhost:5173
    • Should show "Connected" in top right
    • Default home template loaded

  4. Test Real-time Updates 🔄

    • In playground, select "Custom Example" from dropdown
    • Click "Send to App"
    • Watch your app update instantly!

🎨 Try These Examples

Example 1: Change Text

In playground editor:

{
  "screens": [{
    "id": "test",
    "type": "fullscreen",
    "layout": {
      "type": "single-column",
      "placements": [{
        "id": "main",
        "componentIds": ["text-1"],
        "scrollable": false
      }]
    }
  }],
  "components": [{
    "id": "text-1",
    "type": "text",
    "data": {
      "text": "Hello from Playground! 🚀",
      "textAlign": "center"
    },
    "style": {
      "fontSize": 24,
      "marginVertical": 50
    }
  }],
  "metadata": {
    "version": "1.0.0",
    "timestamp": "2024-01-01T00:00:00Z"
  }
}

Click "Send to App" → Text updates instantly!

Example 2: Add Button with Alert

{
  "screens": [{
    "id": "button-test",
    "type": "fullscreen",
    "layout": {
      "type": "single-column",
      "placements": [{
        "id": "main",
        "componentIds": ["button-1"],
        "scrollable": false
      }]
    }
  }],
  "components": [{
    "id": "button-1",
    "type": "button",
    "data": {
      "title": "Press Me!",
      "variant": "primary"
    },
    "actions": [{
      "type": "show_alert",
      "trigger": "onPress",
      "payload": {
        "title": "Success!",
        "message": "You clicked the button!"
      }
    }]
  }],
  "metadata": {
    "version": "1.0.0",
    "timestamp": "2024-01-01T00:00:00Z"
  }
}

Example 3: List with Items

{
  "screens": [{
    "id": "list-test",
    "type": "fullscreen",
    "layout": {
      "type": "single-column",
      "placements": [{
        "id": "main",
        "componentIds": ["header-1", "list-1"],
        "scrollable": true
      }]
    }
  }],
  "components": [
    {
      "id": "header-1",
      "type": "header",
      "data": { "title": "My List" }
    },
    {
      "id": "list-1",
      "type": "list",
      "data": {
        "title": "Items",
        "items": [
          { "id": 1, "title": "First Item", "description": "This is the first item" },
          { "id": 2, "title": "Second Item", "description": "This is the second item" },
          { "id": 3, "title": "Third Item", "description": "This is the third item" }
        ]
      }
    }
  ],
  "metadata": {
    "version": "1.0.0",
    "timestamp": "2024-01-01T00:00:00Z"
  }
}

🐛 Troubleshooting

Server won't start

  • Check port 3001 isn't in use: lsof -i :3001
  • Kill existing process: kill -9 <PID>

Playground won't connect

  • Ensure server is running
  • Check browser console for errors
  • Verify WebSocket URL is correct

App shows error

  • Check IP address is correct (not localhost)
  • Ensure device/simulator is on same network
  • Look at Metro bundler logs

App doesn't update from playground

  • Check "Connected" status in playground
  • Verify WebSocket connection in app logs
  • Look for [WebSocket] logs in React Native debugger

📱 Device vs Simulator

iOS Simulator

  • Use your Mac's IP address
  • WebSocket should work fine

Android Emulator

  • Use 10.0.2.2 instead of localhost
  • Or use your computer's IP if on same network

Physical Device

  • Must be on same WiFi network
  • Use your computer's IP address
  • Check firewall isn't blocking port 3001

🧭 Navigation (Advanced)

The SDUI system supports server-driven navigation with bottom tabs and nested stacks!

Using SDUIAppWithNavigation

Step 1: Update Main App

Replace SDUIApp with SDUIAppWithNavigation in App.tsx:

import { SDUIAppWithNavigation } from './src/sdui';

function App(): React.JSX.Element {
  return <SDUIAppWithNavigation />;
}

export default App;

Step 2: Update Server URLs

In src/sdui/SDUIAppWithNavigation.tsx, replace localhost with your IP:

const SERVER_URL = 'http://YOUR_IP:3001';
const WS_URL = 'ws://YOUR_IP:3001';

Step 3: Test Navigation

In the playground:

  1. Click "Navigation Editor" tab
  2. Select "Bottom Tabs (3 tabs)" template
  3. Click "Send to App"
  4. Your app now has bottom navigation with 3 tabs!

Navigation Templates

The playground includes these navigation templates:

  • Bottom Tabs (3 tabs) - Simple 3-tab layout
  • Bottom Tabs (5 tabs) - Extended 5-tab layout
  • E-commerce App - Shop, Cart, Orders, Account
  • Social Media App - Feed, Explore, Notifications, Messages, Profile

Navigation Features

  • ✅ Bottom Tab Navigation - iOS/Android native tabs
  • ✅ Nested Stack Navigation - Each tab has its own stack
  • ✅ Dynamic Navigation - Update navigation structure from server
  • ✅ Navigation Actions - navigate, goBack, push, replace
  • ✅ Tab Badges - Show notification counts
  • ✅ Custom Icons - Use Ionicons for tab icons

🎯 Next Steps

Once everything works:

  1. Explore Templates - Try all templates in playground (both Screen and Navigation)
  2. Modify JSON - Change text, colors, add components
  3. Test Navigation - Try different navigation structures
  4. Create Custom Components - See README.md
  5. Add Custom Actions - Extend functionality
  6. Build Real Screens - Create your app's UI

📚 Learn More

  • Full Documentation: README.md
  • Implementation Guide: docs/sdui-implementation-doc.md
  • Technical Deep Dive: docs/sdui-technical-deep-dive.md

🎉 Congratulations! You now have a fully working SDUI system!