Frontend Integration

Diosc provides web components that work with any JavaScript framework. This section covers framework-specific integration patterns and common challenges.

Installation

NPM (Recommended for Production)

npm install @diosc-ai/assistant-kit

CDN (Quick Start)

<script type="module" src="https://unpkg.com/@diosc-ai/assistant-kit@latest/dist/assistant-kit/assistant-kit.esm.js"></script>

Available Components

Component	Description	Use Case
<diosc-chat>	Full chat interface	Primary chat experience
<diosc-agent>	Headless agent	Custom UI, background tasks
<diosc-form>	AI-enhanced form	Intelligent form completion
<diosc-action-button>	Context-aware button	Quick actions

Core API

All frameworks use the same core diosc() function:

import { diosc } from '@diosc-ai/assistant-kit';

// Configure connection
diosc('config', {
  backendUrl: 'https://your-hub.example.com',
  apiKey: 'your-api-key',
  autoConnect: true
});

// Set up authentication
diosc('auth', async () => ({
  headers: {
    'Authorization': `Bearer ${getAccessToken()}`
  }
}));

// Listen to events
diosc('on', 'message', (msg) => console.log('AI:', msg.content));
diosc('on', 'error', (err) => console.error('Error:', err));

// Send messages programmatically
diosc('send', 'Hello, AI!');

TypeScript Support

Install types for full IDE support:

npm install -D @types/diosc-client

import type { DioscConfig, DioscMessage, DioscEvent } from '@types/diosc-client';

const config: DioscConfig = {
  backendUrl: 'https://your-hub.example.com',
  apiKey: 'your-api-key'
};

diosc('on', 'message', (msg: DioscMessage) => {
  console.log(msg.content);
});

Common Integration Patterns

Authentication Provider

The auth provider is called before each request:

diosc('auth', async () => {
  // Get current token (refresh if needed)
  const token = await getValidToken();

  return {
    headers: {
      'Authorization': `Bearer ${token}`
    },
    userId: getCurrentUserId()
  };
});

Page Context Updates

Inform the AI about the current page:

// Call when route changes
function updatePageContext(route) {
  diosc('pageContext', {
    path: route.path,
    pageType: route.meta?.pageType,
    pageData: extractRelevantData(route)
  });
}

Custom Event Handling

// Tool execution started
diosc('on', 'tool_start', (tool) => {
  showSpinner(`Executing ${tool.name}...`);
});

// Tool execution completed
diosc('on', 'tool_end', (result) => {
  hideSpinner();
});

// Approval required
diosc('on', 'approval_required', (request) => {
  showApprovalDialog(request);
});

// Session ended
diosc('on', 'session_ended', (reason) => {
  if (reason === 'auth_expired') {
    redirectToLogin();
  }
});

Styling

Customize appearance with CSS variables:

diosc-chat {
  /* Colors */
  --diosc-primary-color: #0066cc;
  --diosc-background: #ffffff;
  --diosc-text-color: #333333;
  --diosc-border-color: #e0e0e0;

  /* Typography */
  --diosc-font-family: 'Inter', sans-serif;
  --diosc-font-size: 14px;

  /* Layout */
  --diosc-border-radius: 8px;
  --diosc-chat-width: 400px;
  --diosc-chat-height: 600px;

  /* Shadows */
  --diosc-shadow: 0 4px 12px rgba(0, 0, 0, 0.15);
}

Common Challenges

Web Components in Frameworks

Web components require special handling in some frameworks:

Issue	Solution
Unknown element warnings	Configure framework to ignore diosc-* elements
Two-way binding	Use events instead of v-model/ngModel
SSR hydration	Render only on client side
TypeScript types	Install @types/diosc-client

See framework-specific guides for details:

• React Integration
• Vue Integration
• Angular Integration
• Vanilla JavaScript

Server-Side Rendering (SSR)

Diosc components require browser APIs. For SSR frameworks:

// Next.js
import dynamic from 'next/dynamic';

const DioscChat = dynamic(
  () => import('@diosc-ai/assistant-kit').then(mod => {
    // Initialize on client
    return () => <diosc-chat />;
  }),
  { ssr: false }
);

// Nuxt
<client-only>
  <diosc-chat />
</client-only>

Multiple Instances

Only one diosc configuration is active at a time:

// ❌ Won't work - second config overwrites first
diosc('config', { apiKey: 'key-1' });
diosc('config', { apiKey: 'key-2' });

// ✅ Use single config with dynamic values
diosc('config', {
  apiKey: getCurrentAssistantKey()
});

Memory Leaks

Clean up on component unmount:

// Store listener references
const unsubscribe = diosc('on', 'message', handleMessage);

// Clean up
onUnmount(() => {
  unsubscribe();
  diosc('disconnect');
});

Next Steps

Choose your framework:

• React - Hooks, context, Next.js
• Vue - Composition API, Nuxt
• Angular - Services, modules, SSR
• Vanilla JS - No framework, pure web components