Skip to content

Widget Development Setup

This guide explains the workflow for developing and testing CSS/UI changes in the Rose widget. For comprehensive technical knowledge about the widget architecture, see Widget Technical Knowledge.

Overview

When making frontend changes to the widget, use this multi-step approach:

  1. Preprod UI (port 3001) - Fast iteration for CSS/UI changes with hot reloading
  2. Widget Demo (port 8083) - Production-like testing with Shadow DOM behavior
  3. Chrome Plugin (optional) - Test website-dependent behavior on real client sites locally
  4. Client Production (optional) - Real production testing on specific client sites

This workflow ensures rapid development while validating changes work correctly in production conditions.

Step 1: Preprod UI Testing (Fast Iteration)

Use the preprod-ui for rapid CSS and UI iteration. It provides hot reloading and can connect to any backend environment.

Starting the Server

cd frontend/preprod-ui
just dev

Or from the frontend root:

cd frontend
just dev-preprod

URL: http://localhost:3001

Benefits

Feature Description
Hot Reloading See changes instantly without page refresh
Direct Package Access Uses @frontend/shared directly (no bundle step)
Environment Flexibility Connect to test, staging, or production APIs
No Local Backend Works with any deployed backend environment

Use Cases

  • CSS tweaks and styling adjustments
  • Component layout changes
  • Theme modifications
  • Responsive design testing
  • Rapid UI prototyping

Connecting to Different Environments

The preprod-ui allows you to select which backend environment to use. No local backend is required - you can test against:

  • Test environment - Safe for experimentation
  • Staging environment - Pre-production validation
  • Production environment - Real data testing (use carefully)

Step 2: Widget Demo Testing (Production Conditions)

After validating changes in preprod-ui, test with the widget demo page. This simulates real-world widget embedding conditions.

Critical: Shadow DOM Differences

The production widget runs inside a Shadow DOM, which isolates its CSS from the host page. Common issues:

  • CSS Variables: Tailwind 4 uses CSS variables (var(--text-sm)) that can inherit from host page
  • rem/em units: Calculated from host page's root font-size, not widget's
  • Font inheritance: Host page fonts don't penetrate shadow boundary
  • Global styles: Don't penetrate the shadow boundary

The widget includes explicit overrides in shadow-dom-protection.css to handle these, but new CSS features should always be tested in the Widget Demo.

Always test CSS changes in the widget demo - what works in preprod-ui may break in production.

Starting the Server

cd frontend/widget
just dev

URL: http://localhost:8083/demo.html

What This Tests

Aspect Description
Shadow DOM CSS isolation behavior (critical for styling)
Full UMD Bundle Tests the production build output
Loader Behavior Validates the widget loader script
Widget Initialization Tests real initialization sequence
Domain Handling Uses localhost.demo which maps to abtasty.com

Environment Configuration

The widget demo uses the test environment API endpoint configured in .env.test. This is hardcoded behavior:

  • Domain: localhost.demo → Forces domain to abtasty.com
  • API: Uses test environment endpoint
  • Bundle: Serves the compiled UMD bundle

Demo Behavior Differences

Environment forceDisplay Traffic Control Hidden Zone
Local demos (just dev) false Can be tested Can be tested
CDN demo pages (just deploy-demo) true Bypassed Bypassed

Local demos load configuration from .env.test and generate demo pages via scripts/build-demo.cjs. Since forceDisplay is false, you can test traffic control and hidden zone features.

CDN demo pages are deployed with forceDisplay: true, meaning the widget always displays regardless of traffic control settings. This is useful for client demonstrations.

Chrome Plugin Testing (Website-Dependent Behavior)

When you need to test behavior that depends on the actual client website, use the Chrome plugin to inject the widget locally. This is useful when testing features that interact with:

  • Specific page navigation or URL detection
  • Form filling and submission tracking
  • Page-specific content or layout interactions
  • Cross-page user journeys
  • Copilot mode on CTA/form pages
  • Page display rules (per-page widget visibility)

How It Works

  1. Build or run the Chrome plugin locally with your changes
  2. Load the unpacked extension in Chrome
  3. Navigate to any client website (e.g., abtasty.com)
  4. The widget injects locally - no deployment needed, no changes to the client's site

Option A: Development Mode (Hot Reload)

For active development with hot-reloading:

cd frontend/chrome-plugin
just dev

This starts a WXT dev server that reloads the extension on code changes. It uses local Supabase (.env.local) automatically.

Then load the unpacked extension from frontend/chrome-plugin/.output/chrome-mv3/ in Chrome (chrome://extensions → "Load unpacked").

Option B: Static Build

For testing a production-like build on real client sites:

cd frontend/chrome-plugin
just build test        # Uses test backend API
just build production  # Uses production backend API
just build staging     # Uses staging backend API

Then load the unpacked extension from frontend/chrome-plugin/.output/chrome-mv3/ in Chrome (chrome://extensions → "Load unpacked").

Local Supabase Auto-Detection

If a local Supabase is running at 127.0.0.1:54321, just build automatically uses it regardless of the environment you specify. This means just build test gives you the test backend API with your local Supabase data (page display rules, site configs, etc.). No extra parameter needed.

Loading the Extension in Chrome

  1. Open chrome://extensions
  2. Enable Developer mode (top-right toggle)
  3. Click Load unpacked
  4. Select the frontend/chrome-plugin/.output/chrome-mv3/ directory
  5. After rebuilding, click the refresh icon on the extension card to reload

Testing Page Display Rules

Page display rules (per-page widget visibility) are stored in Supabase. To test them locally:

  1. Start local Supabase: cd supabase && just start
  2. Configure rules in local Supabase (via backoffice or direct DB edit)
  3. Build or run: just build test or just dev — both use local Supabase automatically
  4. Navigate to the configured URL and verify the widget hides/shows correctly

Testing Form Assistant

Form assistant (copilot mode) requires both conditions to be true:

  1. The unified form_assistant feature is enabled for the domain
  2. The current page is a form tracking page (CTA destination, additional form tracking page, or thank-you page)

To test form assistant locally:

  1. Ensure the feature flag is enabled in the database
  2. Navigate to a configured CTA destination page (e.g., a signup or demo booking page)
  3. The widget should appear as a "Need help?" button in the bottom-right corner
  4. Clicking it should expand to a right-side panel with a welcome message and follow-up questions

See Widget Display Logic - Form Assistant for the complete decision flow.

Source Overrides (Testing Local Changes on Live Sites)

Chrome DevTools source overrides let you replace the production widget bundle on any live client website with a local debug build. This is useful for reproducing and debugging issues in the exact context of a client's site — with their page layout, scripts, and configuration — without deploying anything.

Prerequisites

  • Google Chrome (or any Chromium-based browser)
  • A local debug build of the widget

1. Build the widget in debug mode

cd frontend/widget
just build-debug test

This produces frontend/widget/dist/inboundx-widget.js with debug logging enabled.

2. Enable source overrides in DevTools

  1. Open Chrome DevTools (Cmd+Option+I / Ctrl+Shift+I)
  2. Go to Sources > Overrides tab (in the left sidebar)
  3. Click Select folder for overrides and choose (or create) a local folder
  4. When prompted, click Allow to grant Chrome write access to that folder

3. Override the widget bundle

  1. Go to the Network tab
  2. Reload the page if needed so requests appear
  3. Find the inboundx-widget.js request (filter by "inboundx" to find it quickly)
  4. Right-click the request and select Override content
  5. DevTools opens the file in the Sources editor

4. Replace with your local build

  1. Open the built file at frontend/widget/dist/inboundx-widget.js
  2. Select all its content and copy it
  3. In DevTools, select all content in the override file and paste your build
  4. Press Cmd+S / Ctrl+S to save

5. Hard-refresh the page

Press Cmd+Shift+R / Ctrl+Shift+R to reload without cache. The page now loads your local widget build instead of the production bundle. Debug logs appear in the console.

The override persists across reloads

Chrome remembers overrides until you disable them. To stop overriding, uncheck the Enable Local Overrides checkbox in the Sources > Overrides tab.

Remember to disable overrides

Overrides affect all pages served from the same origin. Disable them when you're done testing to avoid confusion.

Step 3: Client Production Testing (Optional)

Very optionaly. For final validation, you can deploy to specific client sites in production. Not all clients use the same widget bundle, allowing safe in-production testing.

Available Test Sites

Client Domain Notes
Rose userose.ai Our own website - safest for testing
AB Tasty abtasty.com Uses its own widget deployment

When to Use

  • Final validation before rolling out to all clients
  • Testing client-specific configurations
  • Verifying behavior with real production traffic
  • A/B testing widget changes

Deployment

Deploy a new widget version to a specific client before rolling out globally. This allows:

  • Real user interaction testing
  • Production API integration validation
  • Performance monitoring under real conditions

Use with caution

Production testing affects real users. Always test thoroughly in preprod-ui and widget demo first.

Ports Reference

Service Port URL Purpose
Widget Demo 8083 http://localhost:8083/demo.html Production-like testing
Preprod UI 3001 http://localhost:3001 Fast UI iteration

Typical Development Flow

graph LR A[Make CSS/UI changes] --> B[Test in Preprod UI<br/>Port 3001] B --> C{Changes work?} C -->|No| A C -->|Yes| D[Test in Widget Demo<br/>Port 8083] D --> E{Production behavior OK?} E -->|No| A E -->|Yes| F{Need live site context?} F -->|Yes| G[Source Overrides<br/>on client site] G --> H{Works on live site?} H -->|No| A H -->|Yes| I{High-risk change?} F -->|No| I I -->|No| J[Commit & Deploy] I -->|Yes| K[Deploy to test client<br/>userose.ai] K --> L{Real production OK?} L -->|No| A L -->|Yes| J
  1. Start preprod-ui - Begin with fast iteration
  2. Make changes - Edit shared components or styles
  3. Verify in preprod-ui - Check changes with hot reload
  4. Test in widget demo - Validate production bundle behavior
  5. Source overrides (optional) - Test your build on a live client site via DevTools overrides
  6. Deploy to test client (optional) - For high-risk changes, deploy to userose.ai first
  7. Commit & deploy - Roll out to all clients