Plugin Deployment & Testing

Build Script Review

Let's review the esbuild configuration from Day 13:

// build.mjs
import * as esbuild from 'esbuild';

await esbuild.build({
  entryPoints: ['src/index.tsx'],
  bundle: true,
  outfile: 'dist/index.esm.js',
  format: 'esm',
  minify: true,              // Minify for production
  sourcemap: true,           // Generate sourcemaps for debugging
  target: ['es2020'],
  external: [
    'react',
    'react-dom',
    '@empowernow/ui',
    '@empowernow/crud-ui',
    '@experience/plugin-auth'
  ],
  define: {
    'process.env.NODE_ENV': '"production"'
  }
});

Run the Build

# Navigate to plugin directory (replace <YourRepoRoot> with your project root)
# Windows
cd <YourRepoRoot>\experience\plugins\role-viewer\1.0.0

# macOS/Linux
cd <YourRepoRoot>/ServiceConfigs/BFF/plugins/role-viewer/1.0.0

# Install dependencies (if not done)
npm install

# Run the build
npm run build

# Verify output
dir dist   # Windows — or: ls dist (macOS/Linux)

# Expected output:
#   index.esm.js      (bundled code, ~15-50KB)
#   index.esm.js.map  (sourcemap for debugging)

Build Output Analysis

# Check bundle size
(Get-Item dist\index.esm.js).Length / 1KB

# If bundle is too large (>100KB), check for:
# - Accidentally bundled external dependencies
# - Large libraries that should be external
# - Development-only code not tree-shaken

Add Integrity Script to package.json

{
  "scripts": {
    "build": "node build.mjs",
    "integrity": "node -e \"const crypto = require('crypto'); const fs = require('fs'); const hash = crypto.createHash('sha256').update(fs.readFileSync('dist/index.esm.js')).digest('base64'); console.log('sha256-' + hash);\"",
    "deploy": "npm run build && npm run integrity"
  }
}

Generate the Hash

# Run integrity script
npm run integrity

# Output example:
# sha256-abc123def456ghi789jkl012mno345pqr678stu901vwx234=

Update Plugin Manifest

# ServiceConfigs/BFF/config/plugins/manifests/role-viewer.yaml
id: role-viewer
title: "Role Viewer"
version: 1.0.0

bundle:
  file: index.esm.js
  # Update this after every build!
  integrity: sha256-abc123def456ghi789jkl012mno345pqr678stu901vwx234=

# ... rest of config

Automated Deploy Script

// deploy.mjs - Full deploy automation
import * as esbuild from 'esbuild';
import { createHash } from 'crypto';
import { readFileSync, writeFileSync } from 'fs';
import { parse, stringify } from 'yaml';

// 1. Build
await esbuild.build({
  entryPoints: ['src/index.tsx'],
  bundle: true,
  outfile: 'dist/index.esm.js',
  format: 'esm',
  minify: true,
  sourcemap: true,
  target: ['es2020'],
  external: ['react', 'react-dom', '@empowernow/ui', '@empowernow/crud-ui', '@experience/plugin-auth']
});

// 2. Generate integrity hash
const bundle = readFileSync('dist/index.esm.js');
const hash = createHash('sha256').update(bundle).digest('base64');
const integrity = `sha256-${hash}`;

// 3. Update plugins.yaml
const yamlContent = readFileSync('plugins.yaml', 'utf8');
const config = parse(yamlContent);
config.bundle.integrity = integrity;
writeFileSync('plugins.yaml', stringify(config));

console.log('✅ Build complete');
console.log(`📦 Bundle size: ${(bundle.length / 1024).toFixed(1)}KB`);
console.log(`🔒 Integrity: ${integrity}`);

Deployment Structure

The Experience Platform serves plugins from a specific directory structure:

experience/
└── plugins/
    └── role-viewer/
        └── 1.0.0/
            ├── plugins.yaml      # Plugin manifest
            └── dist/
                ├── index.esm.js  # Bundle
                └── index.esm.js.map

Copy Files to Deploy Location

# Windows (PowerShell) — replace <YourRepoRoot> with your project root
$target = "<YourRepoRoot>\experience\plugins\role-viewer\1.0.0"
New-Item -ItemType Directory -Force -Path "$target\dist"
Copy-Item "dist\index.esm.js" "$target\dist\"
Copy-Item "dist\index.esm.js.map" "$target\dist\"
Copy-Item "plugins.yaml" "$target\"
dir $target -Recurse

# macOS/Linux
cd <YourRepoRoot>/ServiceConfigs/BFF/plugins/role-viewer/1.0.0
mkdir -p dist
cp dist/index.esm.js dist/index.esm.js.map dist/
cp plugins.yaml .
ls -R

Register Plugin (First Time Only)

If this is a new plugin, add it to the platform's plugin registry:

# ServiceConfigs/BFF/config/plugins/index.yaml (tenant registry)
# Add the plugin id to the enabled list

# ServiceConfigs/BFF/config/plugins/manifests/role-viewer.yaml (per-plugin manifest)
id: role-viewer
title: "Role Viewer"
version: 1.0.0
enabled: true
    
  # ... other plugins

Verify Deployment

# 1. Check bundle is accessible
curl -s "https://experience.self.empowernow.ai/plugins/role-viewer/1.0.0/dist/index.esm.js" | head -c 200

# 2. Check plugins.yaml is readable
curl -s "https://experience.self.empowernow.ai/plugins/role-viewer/1.0.0/plugins.yaml"

# 3. Navigate to plugin route in browser
# https://experience.self.empowernow.ai/role-viewer

Add Watch Mode to esbuild

// build.mjs - Add watch mode
import * as esbuild from 'esbuild';

const isWatch = process.argv.includes('--watch');

const buildOptions = {
  entryPoints: ['src/index.tsx'],
  bundle: true,
  outfile: 'dist/index.esm.js',
  format: 'esm',
  minify: !isWatch,  // Don't minify in dev
  sourcemap: true,
  target: ['es2020'],
  external: ['react', 'react-dom', '@empowernow/ui', '@empowernow/crud-ui', '@experience/plugin-auth']
};

if (isWatch) {
  const ctx = await esbuild.context(buildOptions);
  await ctx.watch();
  console.log('👀 Watching for changes...');
} else {
  await esbuild.build(buildOptions);
  console.log('✅ Build complete');
}

Update package.json Scripts

{
  "scripts": {
    "dev": "node build.mjs --watch",
    "build": "node build.mjs",
    "integrity": "node -e \"...\"",
    "deploy": "npm run build && npm run integrity"
  }
}

Start Development Mode

# Start watching
npm run dev

# Output:
# 👀 Watching for changes...

# Now edit src/index.tsx - bundle rebuilds automatically!

Local Plugin Override (Optional)

For faster iteration, you can override the plugin URL to load from localhost:

// In browser console on Experience Platform
localStorage.setItem('plugin_override_role-viewer', 'http://localhost:8080/dist/index.esm.js');

// Serve locally with a simple HTTP server
npx serve dist -p 8080 --cors

// Clear override when done
localStorage.removeItem('plugin_override_role-viewer');

Console Debugging

// Add strategic console logs
export function Dashboard() {
  console.log('[RoleViewer] Dashboard mounting');
  
  const fetchRoles = async () => {
    console.log('[RoleViewer] Fetching roles...');
    try {
      const response = await sdk.api.fetch('/api/membership/users/me/roles');
      console.log('[RoleViewer] Response status:', response.status);
      const data = await response.json();
      console.log('[RoleViewer] Roles received:', data);
    } catch (err) {
      console.error('[RoleViewer] Fetch error:', err);
    }
  };
}

Network Tab Investigation

Sourcemap Debugging

With sourcemaps enabled, you can debug original TypeScript code:

// 1. Open DevTools → Sources tab
// 2. Find your plugin under webpack:// or file://
// 3. Navigate to src/index.tsx
// 4. Click line number to set breakpoint
// 5. Refresh page → execution pauses at breakpoint

React DevTools

Install the React DevTools browser extension to inspect:

• Component tree: Find your plugin components
• Props: See what data components receive
• State: Inspect useState/useReducer values
• Hooks: See effect dependencies and values

Common Debug Patterns

// Debug authorization issues
const checkAuth = async () => {
  const request = {
    resource: { type: 'role-viewer.roles' },
    action: { name: 'view' }
  };
  console.log('[Auth] Request:', JSON.stringify(request, null, 2));
  
  const result = await sdk.authz.evaluate(request);
  console.log('[Auth] Result:', JSON.stringify(result, null, 2));
  
  return result.decision === true;
};

// Debug API response parsing
const fetchRoles = async () => {
  const response = await sdk.api.fetch('/api/membership/users/me/roles');
  const text = await response.text();  // Get raw text first
  console.log('[API] Raw response:', text);
  
  try {
    const data = JSON.parse(text);
    console.log('[API] Parsed data:', data);
    return data;
  } catch (e) {
    console.error('[API] Parse error - response was not JSON:', text);
    throw e;
  }
};