Hypershadow Widget

Chat widget for Hypershadow platform with WebSocket communication.

Requirements

• Node.js 18 or higher

Building the project

# Install dependencies
npm i

# Build the main demo app (for local development)
npm run build

# Build library bundle (used as npm package entry)
npm run build:lib

# Build standalone bundle (for script tag / external embedding)
npm run build:vanilla

# Build everything
npm run build:all

Build output will be located in the /dist directory:

• dist/lib – library build used by @yartsun/hypershadow-widget
• dist/standalone – standalone build (IIFE + ES module)

Library usage (ESM / TypeScript)

Install the package:

npm i @yartsun/hypershadow-widget

Use the library entry (components/helpers from dist/lib), for example:

import { /* your exports */ } from '@yartsun/hypershadow-widget';

Standalone entry (ESM)

For embedding the widget into any host app (Nuxt, React, vanilla, etc.) you can use the standalone entry that is now exported via package exports:

import { mount } from '@yartsun/hypershadow-widget/standalone';

mount({
  target: '#chat-widget',
  props: {
    isEmbedded: true,
    isPreview: true,
    // link: 'wss://your-websocket-server.com/chat',
    // configWidget: { ... }
  },
});

This entry is backed by:

• JS: dist/standalone/hs-widget.es.js
• Types: types/standalone.d.ts

ESM usage examples

Nuxt / Vue (client-only mount):

// Any client-only hook (e.g. onMounted in a component)
import { mount } from '@yartsun/hypershadow-widget/standalone';

onMounted(() => {
  mount({
    target: '#chat-widget',
    props: {
      isEmbedded: true,
      isPreview: true,
    },
  });
});

Plain ESM/TypeScript app:

import { mount } from '@yartsun/hypershadow-widget/standalone';

document.addEventListener('DOMContentLoaded', () => {
  mount({
    target: '#chat-widget',
    props: {
      link: 'wss://your-websocket-server.com/chat',
    },
  });
});

For <script>/IIFE-based usage and more advanced configuration examples, see STANDALONE.md.

Module Federation Usage

Using the chat component in another application

1. Import the federated component:

// In your host application
const ChatWrapper = React.lazy(() => import('chat/chat'));

// Or for Vue 3
import { defineAsyncComponent } from 'vue';
const ChatWrapper = defineAsyncComponent(() => import('chat/chat'));

2. Pass WebSocket link via props (recommended for federation):

<template>
  <ChatWrapper 
    :config="chatConfig" 
    :link="websocketUrl"
    :is-embedded="true"
    :is-preview="false" 
  />
</template>

<script setup>
const websocketUrl = "wss://your-websocket-server.com/chat";
const chatConfig = {
  // ... your configuration
};
</script>

3. Alternative: Pass link via URL parameters:

http://your-app.com/chat?link=wss://your-websocket-server.com/chat

Troubleshooting Federation Issues

If you're experiencing WebSocket connection issues when using through federation:

1. Check WebSocket URL format:

   • Must start with ws:// or wss://
   • URL should be properly encoded if passed via query parameters

2. Use props instead of URL parameters:

   <!-- Recommended approach -->
   <ChatWrapper :link="websocketUrl" :config="config" />

3. Enable debugging:

   • Open browser console to see detailed connection logs
   • Component will show which link source is being used

4. CORS considerations:

   • Ensure your WebSocket server allows connections from the federation host domain
   • Check browser network tab for any blocked requests

Props Reference

• link?: string - WebSocket server URL (highest priority)
• config: WidgetConfig - Widget configuration object (required)
• isEmbedded?: boolean - Whether widget is embedded in another app
• isPreview?: boolean - Preview mode (shows placeholder content)