gh-jamshu-jamshi-marketplace-plugins-odoo-pwa-generator/skills/create-odoo-pwa/SKILL.md

---
name: create-odoo-pwa
description: Generate an offline-first Progressive Web App with Odoo Studio backend integration. Use when user wants to create new Odoo-backed application, mentions "PWA with Odoo", "offline Odoo app", "Odoo Studio PWA", or similar terms. Supports SvelteKit, React, and Vue frameworks.
allowed-tools: Read, Write, Glob, Bash
---

# Create Odoo PWA Application

Generate a production-ready Progressive Web App with Odoo Studio backend, featuring offline-first architecture, smart caching, and automatic synchronization.

## Before You Start

This skill generates a complete PWA project following proven architectural patterns:
- **Three-layer data flow**: Component → Cache Store → API Client → Server Route → Odoo
- **Offline-first**: IndexedDB/localStorage with background sync
- **Smart caching**: Incremental fetch, stale detection, optimistic updates
- **PWA-ready**: Service workers, manifest, installable

## Required User Input

Ask the user for the following information before generating:

1. **Project name** (required)
   - Format: kebab-case (e.g., "inventory-tracker", "expense-manager")
   - Used for directory name and package.json

2. **Framework** (required)
   - Options: `sveltekit` (recommended), `react`, `vue`
   - Default: sveltekit if not specified

3. **Primary Odoo model** (required)
   - The main custom model name WITHOUT the `x_` prefix
   - Example: If Odoo model is `x_inventory`, user provides: `inventory`
   - Will automatically add `x_` prefix in code

4. **Model display name** (required)
   - Human-readable singular name (e.g., "Inventory Item", "Expense")

5. **Deployment target** (optional)
   - Options: `vercel`, `github-pages`, `cloudflare`, `netlify`
   - Default: vercel if not specified

## Generation Steps

### Step 1: Project Initialization

Create the project directory and initialize the structure:

```bash
mkdir {{PROJECT_NAME}}
cd {{PROJECT_NAME}}
```

Generate the appropriate structure based on framework:
- **SvelteKit**: Use SvelteKit 2.x structure with `src/` directory
- **React**: Use Vite + React structure
- **Vue**: Use Vite + Vue structure

### Step 2: Base Configuration Files

Generate these files using templates from `skills/create-odoo-pwa/templates/{{FRAMEWORK}}/base/`:

#### For SvelteKit:
- `package.json` - Dependencies including @sveltejs/kit, @vite-pwa/sveltekit, @sveltejs/adapter-static
- `svelte.config.js` - SvelteKit configuration with adapter-static
- `vite.config.js` - Vite + PWA plugin configuration
- `jsconfig.json` or `tsconfig.json` - Path aliases and compiler options

#### For React:
- `package.json` - Dependencies including React 18, Vite, vite-plugin-pwa
- `vite.config.js` - React + PWA plugin configuration
- `tsconfig.json` - TypeScript configuration

#### For Vue:
- `package.json` - Dependencies including Vue 3, Vite, vite-plugin-pwa
- `vite.config.js` - Vue + PWA plugin configuration
- `tsconfig.json` - TypeScript configuration

### Step 3: Environment and Git Configuration

Create `.env.example`:
```env
# Odoo Instance Configuration
ODOO_URL=https://your-instance.odoo.com
ODOO_DB=your-database-name
ODOO_USERNAME=your-username
ODOO_API_KEY=your-api-key

# Primary Model (use x_ prefix)
ODOO_PRIMARY_MODEL=x_{{MODEL_NAME}}

# Optional: For static hosting (GitHub Pages, etc.)
PUBLIC_API_URL=
```

Create `.gitignore`:
```
node_modules/
.env
dist/
build/
.svelte-kit/
.vercel/
.DS_Store
*.log
```

### Step 4: Core Library Files

Generate these essential files from templates:

#### A. Odoo API Client (`src/lib/odoo.js`)
Features:
- API URL configuration (supports PUBLIC_API_URL for static hosts)
- `callApi(action, data)` - Core API communication
- `createRecord(model, fields)` - Create records
- `searchRecords(model, domain, fields)` - Search/read records
- `updateRecord(model, id, values)` - Update records
- `deleteRecord(model, id)` - Delete records
- `formatMany2one(id)` - Format single relation fields
- `formatMany2many(ids)` - Format multi-relation fields
- Model-specific convenience methods

#### B. IndexedDB Manager (`src/lib/db.js`)
Features:
- Database initialization with versioning
- Store definitions for master data (partners, categories, config)
- CRUD operations: `add()`, `get()`, `getAll()`, `update()`, `remove()`
- Transaction helpers
- Error handling

#### C. Smart Cache Store (`src/lib/stores/{{MODEL_NAME}}Cache.js`)
Features:
- Framework-specific store pattern (Svelte store/React context/Vue composable)
- Dual storage strategy (localStorage for metadata, IndexedDB for master data)
- `initialize()` - Load cache and start background sync
- `sync(forceFullRefresh)` - Incremental sync with Odoo
- `forceRefresh()` - Clear cache and full sync
- Partner name resolution with caching
- Optimistic UI updates
- Stale detection (5-minute cache validity)
- Background sync (3-minute intervals)
- Derived stores for UI states

#### D. Utility Functions (`src/lib/{{MODEL_NAME}}Utils.js`)
Features:
- Business logic calculations
- Data normalization helpers
- Field formatters

### Step 5: Server-Side API Proxy

#### For SvelteKit: `src/routes/api/odoo/+server.js`
Features:
- JSON-RPC client for Odoo
- UID caching to reduce auth calls
- `execute(model, method, args, kwargs)` helper
- POST request handler with actions:
  - `create` - Create new record
  - `search` - Search and read records
  - `search_model` - Search any Odoo model
  - `update` - Update existing record
  - `delete` - Delete record
- Error handling with descriptive messages
- Environment variable access

#### For React/Vue: `src/api/odoo.js` (server endpoint)
Similar functionality adapted to framework conventions

### Step 6: UI Components and Routes

Generate starter components and pages:

#### SvelteKit Routes:
- `src/routes/+layout.svelte` - Root layout with navigation
- `src/routes/+layout.js` - SSR/CSR configuration (ssr: false, csr: true)
- `src/routes/+page.svelte` - Main form for creating records
- `src/routes/list/+page.svelte` - List/table view with filtering
- `src/app.html` - HTML template with PWA meta tags

#### React/Vue Pages:
Equivalent component structure adapted to framework conventions

#### Shared Components:
- `OfflineBanner` - Shows online/offline status
- `SyncStatus` - Displays sync state and last sync time
- `LoadingSpinner` - Loading indicator
- Form components with offline support

### Step 7: PWA Configuration

Generate PWA files:

#### `static/manifest.json` (or `public/manifest.json`):
```json
{
  "name": "{{PROJECT_NAME}}",
  "short_name": "{{PROJECT_NAME}}",
  "description": "{{MODEL_DISPLAY_NAME}} management app",
  "start_url": "/",
  "display": "standalone",
  "background_color": "#ffffff",
  "theme_color": "#667eea",
  "icons": [
    {
      "src": "/icon-192.png",
      "sizes": "192x192",
      "type": "image/png"
    },
    {
      "src": "/icon-512.png",
      "sizes": "512x512",
      "type": "image/png"
    }
  ]
}
```

Configure service worker in `vite.config.js`:
- Auto-update strategy
- Cache all static assets
- Offline support

### Step 8: Deployment Configuration

Generate deployment files based on target:

#### Vercel (`vercel.json`):
```json
{
  "buildCommand": "npm run build",
  "outputDirectory": "build",
  "framework": "sveltekit",
  "regions": ["iad1"]
}
```

#### GitHub Pages (`.github/workflows/deploy.yml`):
```yaml
name: Deploy to GitHub Pages
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
      - run: npm ci
      - run: npm run build
      - uses: actions/upload-pages-artifact@v2
        with:
          path: build
```

#### Cloudflare/Netlify:
Generate appropriate configuration files

### Step 9: Documentation

Generate comprehensive documentation:

#### `README.md`:
- Project overview
- Prerequisites (Node.js, Odoo account)
- Installation steps
- Odoo Studio model setup instructions
- Development commands
- Deployment guide
- Architecture overview

#### `CLAUDE.md`:
Complete architecture documentation following the expense-split-pwa pattern:
- Project overview
- Development commands
- Environment setup
- Architecture diagrams
- Key architectural patterns
- Odoo model structure
- Important development notes
- Common gotchas

#### `API.md`:
- Odoo integration patterns
- Available API methods
- Field formatting examples
- Common operations

### Step 10: Post-Generation Instructions

After generating all files, provide the user with:

```
✅ Project '{{PROJECT_NAME}}' generated successfully!

📋 Next Steps:

1. Navigate to the project:
   cd {{PROJECT_NAME}}

2. Install dependencies:
   npm install

3. Configure Odoo credentials:
   cp .env.example .env
   # Edit .env with your Odoo instance details

4. Create Odoo Studio Model:
   - Log into your Odoo instance
   - Go to Studio
   - Create a new model named: x_{{MODEL_NAME}}
   - Add custom fields with x_studio_ prefix
   - Example fields:
     * x_name (Char) - Required
     * x_studio_description (Text)
     * x_studio_value (Float)
     * x_studio_date (Date)
     * x_studio_category (Many2one → res.partner or custom)

5. Start development server:
   npm run dev

6. Generate PWA icons:
   - Create 192x192 and 512x512 PNG icons
   - Place in static/ or public/ directory
   - Name them icon-192.png and icon-512.png

7. Deploy (optional):
   - Vercel: vercel
   - GitHub Pages: Push to main branch
   - Cloudflare: wrangler deploy
   - Netlify: netlify deploy

📚 Documentation:
- README.md - Getting started guide
- CLAUDE.md - Architecture documentation
- API.md - Odoo integration patterns

🔗 Resources:
- Odoo API Docs: https://www.odoo.com/documentation/
- SvelteKit Docs: https://kit.svelte.dev/
```

## Template Variables

When generating files, replace these placeholders:

- `{{PROJECT_NAME}}` - User's project name (kebab-case)
- `{{MODEL_NAME}}` - Odoo model name without x_ prefix
- `{{MODEL_DISPLAY_NAME}}` - Human-readable model name
- `{{FRAMEWORK}}` - sveltekit/react/vue
- `{{DEPLOYMENT_TARGET}}` - vercel/github-pages/cloudflare/netlify
- `{{AUTHOR_NAME}}` - User's name (if provided)

## Common Patterns from expense-split-pwa

This skill implements proven patterns from the expense-split-pwa project:

1. **Smart Caching**: Load from cache immediately, sync in background if stale
2. **Incremental Fetch**: Only fetch records with `id > lastRecordId`
3. **Partner Resolution**: Batch-fetch and cache partner names
4. **Dual-Phase Calculation**: Process settled/unsettled records separately
5. **Optimistic Updates**: Update UI immediately, sync to server in background
6. **Error Recovery**: Graceful degradation when offline

## Error Handling

If generation fails:
- Verify all required input is provided
- Check template files exist
- Ensure proper permissions for file creation
- Provide clear error messages to user

## Framework-Specific Notes

### SvelteKit
- Use Svelte 5 runes syntax (`$state`, `$derived`, `$effect`)
- Configure adapter-static for static deployment
- Set `ssr: false` for client-side only apps
- Use `$app/paths` for base path support

### React
- Use React 18+ with hooks
- Context API for global state
- React Query for server state (optional)
- Vite for build tooling

### Vue
- Use Vue 3 Composition API
- Pinia for state management
- Composables for reusable logic
- Vite for build tooling

## Testing the Generated Project

After generation, verify:
1. `npm install` completes without errors
2. `npm run dev` starts development server
3. Form renders correctly
4. Offline banner appears when disconnecting
5. Data persists in localStorage/IndexedDB
6. Sync works when back online

## Support

For issues or questions:
- Check CLAUDE.md for architecture details
- Review generated code comments
- Consult Odoo API documentation
- Verify environment variables are set correctly