Merge pull request #165 from objectstack-ai/copilot/add-msw-integration-example

Author: hotlong

examples/ui/msw-react-crud/.gitignore

@@ -0,0 +1,31 @@
+# Dependencies
+node_modules
+pnpm-lock.yaml
+
+# Build outputs
+dist
+build
+*.tsbuildinfo
+
+# Development
+.vite
+.cache
+
+# Environment
+.env
+.env.local
+
+# Editor
+.vscode/*
+!.vscode/extensions.json
+.idea
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# MSW
+public/mockServiceWorker.js

examples/ui/msw-react-crud/CHANGELOG.md

@@ -0,0 +1,18 @@
+# @objectstack/example-msw-react-crud
+
+## 1.0.0
+
+### Major Features
+
+- Initial release of MSW + React CRUD example
+- Complete CRUD operations (Create, Read, Update, Delete) for tasks
+- Integration with @objectstack/client for all API calls
+- MSW browser worker setup for API mocking
+- React components demonstrating best practices:
+  - TaskList component for displaying and managing tasks
+  - TaskForm component for creating and editing tasks
+  - TaskItem component for individual task display
+- Comprehensive README with setup instructions and usage examples
+- Full TypeScript support with proper type definitions
+- Vite development server and build configuration
+- Styled UI with modern CSS

examples/ui/msw-react-crud/QUICKSTART.md

@@ -0,0 +1,171 @@
+# Quick Start Guide - Simplified MSW Integration
+
+This is the **simplified** version using `@objectstack/plugin-msw` that auto-mocks all API endpoints. No manual handler code required!
+
+## Prerequisites
+
+- Node.js 18 or later
+- pnpm package manager
+
+## Step 1: Install Dependencies
+
+From the repository root:
+
+```bash
+pnpm install
+```
+
+## Step 2: Build Required Packages
+
+Build the core packages:
+
+```bash
+# Build all required packages
+pnpm --filter @objectstack/spec build
+pnpm --filter @objectstack/runtime build
+pnpm --filter @objectstack/plugin-msw build
+pnpm --filter @objectstack/client build
+```
+
+## Step 3: Initialize MSW
+
+The MSW service worker file should already be initialized:
+
+```bash
+cd examples/ui/msw-react-crud
+npx msw init public/ --save
+```
+
+## Step 4: Start the Development Server
+
+```bash
+cd examples/ui/msw-react-crud
+pnpm dev
+```
+
+The application will start on `http://localhost:3000`
+
+## ✨ What's Different?
+
+### Before (Manual Approach) ❌
+
+You had to manually write 145+ lines of MSW handlers:
+
+```typescript
+// src/mocks/browser.ts - OLD WAY
+const handlers = [
+  http.get('/api/v1/data/task', ({ request }) => {
+    // Manual pagination, filtering, sorting...
+  }),
+  http.post('/api/v1/data/task', async ({ request }) => {
+    // Manual ID generation, validation...
+  }),
+  // ... more manual handlers
+];
+const worker = setupWorker(...handlers);
+await worker.start();
+```
+
+### After (Plugin Approach) ✅
+
+Now just **3 lines** with auto-mocking:
+
+```typescript
+// src/mocks/browser.ts - NEW WAY
+const mswPlugin = new MSWPlugin({ baseUrl: '/api/v1' });
+const runtime = new ObjectStackKernel([appConfig, mswPlugin]);
+await runtime.start();  // Auto-mocks ALL endpoints!
+```
+
+## 📦 How It Works
+
+1. **Define Your Data Model** in `objectstack.config.ts`:
+   ```typescript
+   const TaskObject = ObjectSchema.create({
+     name: 'task',
+     fields: {
+       subject: Field.text({ required: true }),
+       priority: Field.number()
+     }
+   });
+   ```
+
+2. **Auto-Mock Everything**: The MSW plugin automatically mocks:
+   - ✅ Discovery endpoints
+   - ✅ Metadata endpoints
+   - ✅ All CRUD operations
+   - ✅ Query operations
+   - ✅ Pagination, sorting, filtering
+
+3. **Use ObjectStack Client** normally:
+   ```typescript
+   const client = new ObjectStackClient({ baseUrl: '/api/v1' });
+   await client.data.create('task', { subject: 'New task' });
+   ```
+
+## 🎯 Test CRUD Operations
+
+Once running, you can:
+
+1. **Create** tasks using the form
+2. **Read** tasks in the list
+3. **Update** tasks by clicking "Edit"
+4. **Delete** tasks by clicking "Delete"
+5. **Toggle completion** status
+
+## 🔍 What Gets Auto-Mocked?
+
+The plugin automatically handles:
+
+| Endpoint | Description |
+|----------|-------------|
+| `GET /api/v1` | Discovery |
+| `GET /api/v1/meta/*` | All metadata |
+| `GET /api/v1/data/:object` | Find records |
+| `GET /api/v1/data/:object/:id` | Get by ID |
+| `POST /api/v1/data/:object` | Create |
+| `PATCH /api/v1/data/:object/:id` | Update |
+| `DELETE /api/v1/data/:object/:id` | Delete |
+
+**Zero manual code!** 🎉
+
+## 🔧 Advanced: Custom Handlers
+
+Need custom logic? Easy:
+
+```typescript
+const customHandlers = [
+  http.get('/api/custom/hello', () => 
+    HttpResponse.json({ message: 'Hello!' })
+  )
+];
+
+const mswPlugin = new MSWPlugin({
+  customHandlers,  // Add your custom handlers
+  baseUrl: '/api/v1'
+});
+```
+
+## Troubleshooting
+
+**MSW worker not starting?**
+```bash
+npx msw init public/ --save
+```
+
+**TypeScript errors?**
+```bash
+pnpm --filter @objectstack/spec build
+pnpm --filter @objectstack/runtime build
+pnpm --filter @objectstack/plugin-msw build
+```
+
+**404 errors?**
+Check browser console for MSW startup message
+
+## 📚 Learn More
+
+- Full documentation: [README.md](./README.md)
+- MSW Plugin: `packages/plugin-msw/README.md`
+- Runtime: `packages/runtime/README.md`
+- Client API: `packages/client/README.md`